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About NetYaroze 


What You Need to Know 

In order to get started with Net Yaroze, you should have experience of C programming to a competent level 
and a knowledge of a 2D graphic creation/editing tool. In addition, at least a basic grasp of a 3D modelling 
packageand a sound creation/editing toolwould be help you get the best out of you NetY aroze kit. 

The NetYaroze Manual Set 

There are three books in the set of NetYaroze manuals. 

1 . Start Up Guide 

An introductory booklet explaining the contents and requirements of the NetY aroze Starter Kit. It 
also gives step by step instructions on setting up they NetYaroze software on your PC and how to 
run Net Yaroze software on the system. 

2. User Guide 

A reference manual providing details on making software for the NetY aroze system. 

3. Library Reference (this document) 

A manual listing and describing the functions and structures in the NetYaroze libraries. 


Additional Reading 

Please see the Additional Reading list at the end of theStart Up Guide 






Graphics Functions 




RECT 


Frame buffer rectangular area 


Structure 

typedef struct { 

short x, y; 
short w, h; 

} RECT; 


Members 

x, y Coordinates for the top left-hand comer of the rectangular area 

w, h Width and height of the rectangular area 


Comments 

RECT specifies the area of the frame buffer to be accessed. Negative values or values that 
exceed the size of the frame buffer ( 1 024x5 12) cannot be used. 




DRAWENV 


Drawing environment 


Structure 

typedef struct { 

RECT clip; 
short ofs[2]; 

RECT tw, 

unsigned short tpage; 
unsigned char dtd; 
unsigned char dfe; 
unsigned char isbg; 
unsigned char rO, gO, bO; 

DRENV dr env, 

} DRAWENV; 

Members 

clip Drawing area. Drawing is limited to the rectangular area specified by 

clip. Drawing cannot be performed outside the clip area 
ofs Offset. The values (ofs[0],ofs[l]) are added to all coordinate values to 

give the address values used by all drawing commands when drawing 
in the frame buffer 

tw Texture window. Repeated use is made of the texture pattern 

contained in the rectangular area within the texture page 
defined by tw 
Texture page initial value 


tpage 




dtd 


Dither treatment flag 


0: OFF 

1: ON 

dfe Flag for drawing to the dkplay area 

0: Drawing to the display area is blocked 

1: Drawing to the display area is allowed 

isbg Clear drawing area flag 

0: OFF 

1: ON 

0: The drawing area is not cleared when the drawing 
environment is set up 

1 : The entire clipped area is painted with the brightness 
values (r0,g0,b0) when the drawing environment is set 
up. 

r0,g0,b0 Background colour. Only available whenisbg = 1 . 

dr_env Reserved for this system 

Comments 

DRAWENV sets the basic parameters relating to drawing offset, drawing clip area, etc. 


Notes 

Within the drawing space, drawing can actually be carried out in the region (0, 0)-(1023, 
511). 

Offset values and address values to which the offset has been added are wrapped around 
using (-1024, - 1 024)-( 1 023, 1023). 

Values that can be specified for the texture window are limited to the combinations shown 
in the following table. 


Tw.w 

0(=256) 

16 

32 

64 

128 

tw.x 

0 

multiple of 16 

multiple of 32 

multiple of 64 

multiple of 128 

tw.h 

0(=256) 

16 

32 

64 

128 

tw.y 

0 

multiple of 16 

multiple of 32 

multiple of 64 

multiple of 128 




























DISPENV 


Display environment 


Structure 


typedef struct { 


} DISPENV; 


RECT disp; 

RECT screen; 
unsigned char isinter; 
unsigned char isrgb24; 
unsigned char padO, padl; 


Members 

disp Display area within the frame buffer 

The width of the area can be set to 256, 320, 360, 512 or 640 
The height of the area can be set to 240 or 480 
screen Display area on the output screen 

The screen area is calculated on the basis of a standard monitor screen 
in which the coordinates are (0, 0) for the top left corner and (256, 
240) for the bottom right corner, regardless of thedisp value 
isinter Interlaced mode flag 

0: Non-interlaced 

1: Interlaced 

isrgb24 24bit mode flag 

0: 16bitmode 


1 : 24 bit mode 




Comments 

DISPENV specifies parameters for screen display mode, frame buffer display position, 
etc. 



VECTOR 


32bit 3D vectors 


Structure 

typedef struct { 

long vx, vy, 
long vz, pad; 

} VECTOR; 

Members 

vx, vy, vz Vector components 

pad Padding 

Comments 

VECTOR defines the structure of 32 bit 3D vectors. 




SVECTOR 


16 bit 3D vectors 


Structure 

typedef struct { 

short vx, vy, 
short vz, pad; 

} SVECTOR; 

Members 

vx, vy, vz Vector components 

pad Padding 


Comments 


SVECTOR defines the structure of 16bit 3D vectors. 




CVECTOR 


8bit 3D vectors (colour vectors) 


Structure 


typedef struct { 


} CVECTOR; 


unsigned char r, g, b, cd; 


Members 


r, g, b 


Vector components 


cd 


Padding 


Comments 


CVECTOR defines the structure of 8 bit colour vectors. 




MATRIX 


3x3 matrices 


Structure 

typedef struct { 

short m[3][3]; 
long t[3 ] ; 

} MATRIX; 

Members 

m 3x3 matrix coefficient values 

t Amount of translation 


Comments 

Each component is specified using the m[][j] part of MATRIX. 

The amount of translation after conversion is specified using the tj] part of MATRIX. 




GsOT 


Ordering table headers 


Structure 

struct GsOT { 

unsigned short length; 
GsOTTAG “teg; 
unsigned short offset; 
unsigned short point; 
GsOT TAG “tag; 

}; 

Members 


length 

OT bit length 

org 

Top address of theGsOTTAG table 

offset 

OT offset on the Z axis in the screencoordinate system 

point 

OT representative value on the Z axis in the screen 


coordinate system 

tag 

Pointer to the current top GsOT TAG 


Comments 

GsOT indicates the ordering table header. 

This header holds the pointers, org and tag that point to the actual ordering table, org and 
tag are both initialised using the GsClearOt() function, 
tag points to the top of the ordering table. 




The GsDrawOt() function draws the ordering table to whichtag points. 

The value of tag changes because the top is changed using the GsSortClearQ or 
GsSortOtQ functions, org is therefore provided to continue to hold the top of the ordering 
table. 

The size of the ordering table is set by length, length can be set to any value between 1 
and 14. When length is set to 1, org points to a 0~1 GsOT_TAG array, and when length is 
set to 14, org points to a 0~16384 GsOTTAG array. 

The GsClearOtQ function initialises an area of memory from org up to the size specified 
by length. Accordingly, it is important to be aware that if the size of the GsOT_TAG array 
pointed to by org is less than the size indicated by length, memory may be damaged, 
point refers to the representative value of the ordering table when ordering tables are 
sorted among themselves by means of theGsSortOt() function. 

offset sets the ordering table offset on the Z axis. For example, if offset = 256 the top of 
the ordering table will be at Z = 256. (*1) 


Notes 

The values of length and org must be set at the initialisation stage. The other members are 
set using the GsClearOt() function. 

*1 Not supported at present. 


See also 


GsClearOtQ, GsDrawOt(),GsSortOt(),GsCutOt() 



GsOT TAG 


Ordering table units 


Structure 

struct GsOTTAG { 

unsigned p : 24; 
unsigned char num: 8; 

}; 

Members 

p OT ring pointer 

num Word number packet 

Comments 

The ordering table array will be the array of thisGsOT_TAG. 

The ordering table is the “list structure” that points to successive addresses. In the case of 
the 32bit address, the lower order 24bit can be displayed byp. 

The GsOT_TAG array of the size set by theGsOT member length is secured when the 
ordering table is placed in memory. 


GsD0BJ2 


For GsCOORDINATE2 3D object handler 


Structure 

struct GsDOBJ2 { 

unsigned long attribute, 
GsCOORDINATE2 toord2; 
unsigned long *tmd; 
unsigned long id; 

}; 

Members 


attribute 

Object attribute ( 32bit ) 

coord2 

Pointer to local coordinate system 

tmd 

Pointer to modelling data 

id 

Reserved for the system 


Comments 

3D models can be manipulated via the structure GsDOBJ2, which is used as the handler 
for each 3D model. GsLinkObject4() is used to link GsDOBJ2 to the modelling data of the 
TMD file. 

Access to linked TMD data is possible via GsDOBJ2. GsSortObject4() is used to register 
GsDOBJ2 in the ordering table. 

coord2 is the pointer to the coordinate system inherent in the object. 




The position, gradient and size of the object are reflected in the coordinate system pointed 
by coord2 by setting the matrix. 

tend holds the top address of the modelling data stored in memory in TMD format, tmd is 
calculated and set by GsLinkObject4(). 

attribute is 32bit, and various attributes are set here for the purpose of display. 
Comments on each bit are as follows. 

(a) Light source calculation ON/OFF switch (bit 6) 

This bit is used when the light source calculation is removed. 

Texture-mapped polygons are displayed in original texture colour when the light 
source calculation is removed. Unmapped polygons are displayed in modelling data 
colour as they are. 

(b) Automatic division function switch (bit 9-11) 

0: No automatic division 

1 : 2x2 division 

2: 4x4 division 

3: 8x8 division 

4: 16x16 division 

5: 32x32 division 

This bit specifies the division number of automatic division. Automatic division is the 
function for automatically dividing one polygon at the time of execution. It is used for 
decreasing texture distortion and preventing deficiency in neighbouring polygons. 
However, division should be kept to a minimum in order to increase the number of 
polygons in exponential function terms. 



(c) Semi-transparency ON/OFF (bit30) 

This puts semi-transparency ON/OFF. 

The highest order bit (STP bit) of the texture colour field (texture pattern when direct 
is set, CLUT colour field when indexed is set) must be used together with this bit in 
order to set semi-transparency. Pixel unit semi-transparency/opacity can also be 
controlled by using this STP bit. 

(d) Display ON/OFF (bit31) 

This puts display ON/OFF. 



GsC00RDINATE2 


Matrix type coordinate system 


Structure 

struct GsCOORDINATE2 { 

unsigned long flg; 

MATRIX coord; 

MATRIX workrp 
GsCOORD2PARM *param 
GsCOORDINATE2 %uper; 

}; 


Members 

flg 

coord 

workm 

param 

super 


Flag as to whether or not coord has been rewritten 
Matrix 

The result from this coordinate system to the WORLDcoordinate 
system 

Pointer for using scale, rotation and transfer parameters 
Pointer to the parent coordinates 


Comments 

GsCOORDINATE2 holds parent coordinates and is defined according to the MATRIX 
type coord. 

When the matrix is multiplied by the GsGetLwQ or GsGETLs() function in each node of 
GsCOORDINATE2 from the WORLQoordinates, its result is held in workm 
However, it does not store the result in workm of the coordinate system that is directly 
connected to the WORLDcoordinate system. 




At the time of GsGetLwQ and GsGetLs() calculation, fig is referred to in order to avoid 
calculation of nodes that have already been calculated. 1 is to set, 0 is to clear. 

The programmer must take responsibility for clearing this flag if the content of coord is 
changed. Otherwise, theGsGetLw()andGsGetLs() functions will be defective. 



GsVIEW2 


Viewpoint position (MATRIX type) 


Structure 

struct GsVIEW2 { 


MATRIX view, 
GsCOORDINATE2 %uper 


Members 

view 


super 


Matrix for conversion from parentcoordinates to viewpoint 
coordinates 

Pointer to the coordinate system that sets the viewpoint 


Comments 

GSVIEW2 sets the viewpointcoordinate system. It directly specifies the matrix for 
converting from the parent coordinate system to the viewpointcoordinate system in view. 
The setting function is GsSetView2(). 




GsRVIEW2 


Viewpoint position (REFERENCE type) 


Structure 

~ struct GsRVIEW2 { 


long vpx, vpy, vpz; 
long vpx, vpy, vpz; 
long rz; 

GsCOORDINATE2 $uper 


Members 

vpx, vpy, vpz 
vrx, vry, vrz 
rz 

super 


Viewpoint coordinates 
Reference point coordinates 
Viewpoint twist 

Pointer to the coordinate system that sets the viewpoint 
(GsCOORDINATE2 type) 


Comments 

GsVIEW2 holds the viewpoint information, and is set according to the GsSetRefView2() 
function. 

The coordinates of the viewpoint in the coordinate system displayed by super are set in 
(vpx, vpy, vpz). 

The coordinates of the reference point in the coordinate system displayed by super are set 
in (vrx, vry, vrz). 

rz is specified in fixed decimal point fonnat with the gradient for the screen z axis when 
the z axis is the vector from the viewpoint to the reference point, set so that 4096 is one 
degree. 




The coordinate systems of the viewpoint and reference point are set in super. For 
example, a cockpit view can be easily created with this function by setting super in the 
coordinate system of an aeroplane. 



GsF LIGHT 


Parallel light source 


Structure 

~ struct GsFLIGHT { 

long vx, vy, vz; 
unsigned char r, g, b; 

}; 

Members 

vx, vy, vz Light source direction vectors 

r, g, b Light colours 

Comments 

GsF LIGHT holds parallel light source information and is set in the system by the 
GsSetFlatLight() function. 

Up to three parallel light sources can be set at the same time. 

Sets the direction vectors of the light source in (vx, vy, vz). The programmer does not have 
to carry out standardisation as this is done by theGsSetFlatLight function. 

The light shines strongest on normal vector polygons whose directions are opposite to 
these vectors. 

Sets the colours of the light source in (r,g,b) by 8bit. 




GsFOGPARAM 


Fog (depth queue) information 


Structure 

~ struct GsFOGPARAM { 

short dqa; 
long dqb; 

unsigned char rfc, gfc, bfc; 

}; 

Members 

dqa 
dqb 

rfc, gfc, bfc 

Comments 

dqa and dqb are the attenuation coefficients to the background colour, 
dqa and dqb can be shown according to the following formula. 

dqa = -df * 4096/64/h 
dqb = 1.25 * 4096 * 4096 

df is where the attenuation coefficients become one. In other words it is the distance from 
the viewpoint to the point where the background colour completely merges into the distant 
view. 

h is the distance from the viewpoint to the screen. In other words it indicates the 
projection distance. 


Parameter of the degree of merging in relation to depth 
Parameter of the degree of merging in relation to depth 
Background colours 




GsIMAGE 


Image data configuration information 


Structure 

struct GsIMAGE { 

short pmode; 
short px, py, 
unsigned short pw, ph; 
unsigned long *pixel; 
short cx, cy, 
unsigned short cw, ch; 
unsigned long *clut; 


Members 


pmode 

Pixel mode 



0: 

4bit CLUT 


1: 

8bit CLUT 


2: 

16bit DIRECT 


3: 

24bit DIRECT 


4: 

Other mode mixtures 

px, py 

Pixel data storage positions 

pixel 

Pointer to pixel data 

cx, cy 

CLUT data storage positions 




cw, ch 
clut 


CLUT data width/ height 
Pointer to CLUT data 


Comments 


Gslmage is the structure for storing TIM format data information using the 
GsGetTimlnfoO function. 

For file format, please refer to the NetYaroze Members' Web site. 



GsSPRITE 


Sprite handler 


Structure 


Members 


struct GsSPRITE { 

unsigned long attribute, 


short x, y; 


unsigned short w, h; 


unsigned short tpage; 


unsigned char u, v; 


short cx, cy, 


unsigned char r, g, b; 


short lnx, my, 


short sea lex, sea ley, 

}; 

long rotate; 

attribute 

32bit length attribute (details are given below) 

x>y 

Top left-hand point display positions 

w, h 

Sprite width and height (not displayed when either w or h is 0) 

tpage 

Sprite pattern texture page number 

u, V 

Sprite pattern in-page offset 

cx, cy 

Sprite CLUT address 




r, g, b 


mx, my 
scales scaley 
rotate 

attribute bits 


Brightness is set for each of r, g and b when they 
are displayed (Original brightness when it is 128) 
Rotation/ expansion central coordinates 
x and y direction scaling values 
Rotation angle (Units: 4096 = 1° (degree)) 

6: Brightness regulation 

0: ON 

1: OFF 

24-25: Sprite pattern bit mode 

0: 4bitCLUT 

1: 8bitCLUT 

2: 15bitDirect 

27: Rotation scaling function 
0: ON 

1: OFF 

28-29: Semi-transparency rate 

0: 0.5 x Back + 0.5 x Forward 

1: 1.0 x Back + 1.0 x Forward 

2: 1.0 x Back - 1.0 x Forward 

3: 1.0 x Back + 0.25 x Forward 

30: Semi-transparency ON /OFF 

0: Semi-transparency OFF 

1: Semi-transparency ON 

3 1 : Displayed/ Not displayed 

0: Display 

1: No display 



Comments 


GsSPRITE is the structure that holds information for displaying sprites and prepares one 
for each sprite displayed. The sprites can be operated via the parameters. 

Either GsSortSprite() or GsSortFastSpriteQ may be used to register GsSPRITE in the 
ordering table. 

The on-screen display position is specified as (x, y). The points specified as (mx, my) in 
the sprite pattern are the positions specified in the GsSortSprite() function, and the top 
left-hand points of the sprites are the positions specified in the GsSortFastSprite() 
function. 

The width and length of the sprites are specified in pixel units as (w, h). 

Texture page numbers, where there are sprite patterns, are specified astpage(0~31). 

The top left-hand points of the sprite patterns are specified with in-page offset as d, v). A 
range (0,0)~(255,255) can be specified. 

The top positions of GLUT (Colour palette) are specified by the VRAM address ascfx, 
cy) (only valid at the time of 4bit/8bit). 

Brightness is specified for each of r, g and b as (r, g, b). Values from 0~255 can be 
specified. The brightness of the original pattern is attained at 128 and double the 
brightness at 255. 

Rotation expansion central coordinates are given as (mx, my) as relative coordinates 
whose origins are the top left-hand points of the sprites. For example, one half of the 
width and length is specified if it is rotated at the centre of the sprite. 

The scaling values are given for the x and y directions as (scalex, scaley). The unit is 
4096 = 1.0 (original size). It can be set up to a maximum of eight times, 
rotate sets rotation around the Z axis in fixed decimal point format with 4096 as 1 degree, 
attribute is 32bit in which various attributes are set for display. 

Comments on each bit are as follows. 

(a) Brightness adjustment ON/OFF switch (bit 6) 

This sets whether or not the sprite pattern pixel colours are to be drawn with 
brightness adjusted according to the (r,g,b) values. When it is 1, brightness is not 
adjusted and the (r,g,b) values are disregarded. 



(b) Bit mode (bit 24-25) 

In the sprite patterns there are 4bit and 8bit modes that use colour tables and a 15bit 
mode that displays colour directly. This is specified here. 

(c) Rotation scaling function (bit 27) 

Switches the sprite expansion function ON/OFF. If it is switched off when sprite 
rotation and expansion are not carried out, processing will be speeded up. 

This bit is also disregarded in the case of the GsSortFastSprite() function, and the 
expansion function is always turned OFF. 

(d) Semi-transparency rate (bit 28-29) 

Sets the method of pixel blending when semi-transparency is turned ON with bit 30. 
Normal semi-transparent processing is performed when set to 0, pixel addition when 
set to 1, pixel subtraction when set to 2, and 25% addition when set to 3. 

(e) Semi-transparency ON/OFF (bit 30) 

It turns semi-transparency ON/OFF. 

The highest order bit (STP bit) of the texture colour field (texture pattern when direct 
is set, CLUT colour field when indexed is set) must be used together with this bit in 
order to set semi-transparency. 

Pixel unit semi-transparency/opacity can also be controlled by using this STP bit. 

(f) Display ON/OFF (bit 31) 

Turns display ON/OFF. 



GsBG 


BG (background picture) handler 


Structure 

struct GsBG { 

unsigned long attribute, 
short x, y; 
short w, h; 

short scrollx, scrolly, 
unsigned char r, g, b; 
GsMAP *map; 
short mx, my, 
short sea lex, sea ley, 
long rotate; 


Members 

attribute 
x, y 
w, h 

scrollx, scrolly 
r, g, b 


Attribute 

Display positions of the top left-hand points 
BG display size (pixel unit) 
x,y scroll value 

Brightness is set for each of r, g and b when they are 
displayed (Original brightness when 128) 

Pointer to map data 


map 




mx, my 
scales scaley 
rotate 


Rotation/ expansion central coordinates 
x and y direction scaling values 
Rotation angle (Units: 4096 = 1° (degree)) 


Comments 

BG (Background) is a function for drawing one large rectangle constructed by thGsMAP 
data combining small rectangles defined byGsCELL data. 

BG can be operated via the structure of thisGsBG, which exists in each BG. 

The on-screen display position is specified as (t, y). 

The display size of BG is specified as (w, h). Units are pixels and do not depend on the 
cell size or the size of map. 

The content of the map is also displayed repeatedly if the display area is larger than the 
size of the map. (Tiling function) 

(scrollx, scrolly) are the display position offsets in the map and are specified in dot units. 
Brightness is specified for each of r, g and b as (r, g, b). It becomes the original colour at 
128 and double the brightness at 255. 

map is the pointer to the GsMAP format map data to which the top address of the map 
data is specified. 

Rotation expansion central coordinates are given as (mx, my) as relative coordinates 
whose origins are the top left-hand points of BG. For example, one half of the width and 
length is specified if it is rotated at the centre BG. 

The scaling values are given for the x and y directions as (scalex, scaley). The unit is 
4096 = 1.0 (original size). It can be set up to a maximum of eight times. 

The rotation angle around the z axis is specified asrotate (4096 = 1 degree). 

Please refer to GsSprite regarding attribute. 



GsMAP 


BG composition MAP 


Structure 

struct GsMAP { 


}; 

Members 

cellw, cellh 
ncellw, ncellh 
base 
index 


unsigned char cellw, cellh; 
unsigned short ncellw, ncellh; 

GsCELL ’'base; 
unsigned short *index; 

Cell size (taken as 256 in the case of 0) 
Size of BG (unit is cell) 

Pointer to the GsCELL structure array 
Pointer to the cell array information 


Comments 

GsMAP is map data (cell array information) for composing BG witlGsCELL. The map 
data controls the information by cell index array. 

The size of one cell is specified in pixel units as fcellw, cellh). Note also that one BG is 
formed from a cell of the same size. 

The size of map held by BG is specified in cell units as(ncellw, ncellh). 

The top address of theGsCell array is set as base. 

The top address of the cell array information table is set as index. The cell array 
information indicates the index value for the above array shown in base as ncellw x 
ncellh A NULL cell (transparent cell) is indicated if the index value is Oxffff. 




GsCELL 


BG configuration cell 


Structure 

struct GsCELL { 


unsigned char u, v; 
unsigned short cba; 
unsigned short flag; 
unsigned short tpage; 


Members 


u 

Offset from within the page (X direction) 

V 

Offset from within the page (Y direction) 

cba 

CLUT ID 

flag 

Inversion information 

tpage 

Texture page number 


Comments 

GsCELL is the structure holding information about the cell that composes BG and it is 
secured in the memory as an array. 

The position of the sprite pattern corresponding to its cell is specified as (i, v) by offset in 
the page specified as tpage. 

cba is the data that displays the position within the frame buffer of the CLUT 
corresponding to its cell, as follows. 




Bit 

Value 

bit0~5 

X position of CLUT/16 

bit6 — 1 5 

Y position of CLUT 


flag holds information as to whether or not that cell displays the original texture pattern 
inversely. 


Bit 

Value 

bitO 

Vertical inversion (no inversion when set to 0, inversio 
when set to 1) 

bitl 

Horizontal inversion (no inversion when set to 0, 
inversion when set to 1) 

bit2~ 1 5 

Reserved 


tpage is the page number displaying the position within the frame buffer of the sprite 
pattern. 

















GsLINE 


Straight line handler 


Structure 

struct GsLINE { 

unsigned long attribute, 
short xO, yO; 
short xl, yl; 
unsigned char r, g, b; 

}; 

Members 

attribute Attribute 

28-29: Semi-transparency rate 

0: 0.5 x Back + 0.5 x Forward 

1: 1.0 x Back + 1.0 x Forward 

2: 1.0 x Back - 1.0 x Forward 

3: 1.0 x Back + 0.25 x Forward 

30: Semi-transparency ON OFF 

0: Semi-transparency OFF 

1: Semi-transparency ON 

31: Display ON OFF 

0: Display 

1: No display 




xO, yO 
xl, yl 
r, g, b 


Position of drawing start point 
Position of drawing end point 
Drawing colour 


Comments 

GsLINE is the structure that holds information necessary for drawing straight lines. The 
GsSortLine() function is used to registerGsLINE in the ordering table, 
attribute is 32bit, and various attributes are set here for the purpose of display. 

(a) Semi-transparency rate (bit28-29) 

GsLINE sets the pixel blending method when semi-transparency is turned ON by 
bit30. Normal semi-transparency processing is performed when set to 0, pixel addition 
when set to 1, pixel subtraction when set to 2, and 25% addition when set to 3. 

(b) Semi-transparency ON/OFF (bit30) 

Turns semi-transparency ON/OFF 

(c) Display ON/OFF (bit31) 

Turns display ON/OFF 



GsGLINE 


Gradation straight line handler 


Structure 


struct GsGLINE { 


unsigned long attribute, 
short xO, yO; 
short xl, yl; 
unsigned char rO, gO, bO; 
unsigned char rl,gl,bl; 


Members 


attribute Attribute 

28-29: Semi-transparency rate 


0 : 

1 : 

2 : 

3: 


0.5 x Back + 0.5 x Forward 
.0 x Back + 1 .0 x Forward 
1.0 x Back - 1.0 x Forward 
1.0 x Back + 0.25 x Forward 


30: Semi-transparency ON OFF 

0: Semi-transparency OFF 

1: Semi-transparency ON 

3 1 : Display ON OFF 

0: Display 

1: No display 




xO, yO 

Position of drawing start point 

xl, yl 

Position of drawing end point 

rO, gO, bO 

Start point drawing colour 

rl, gl, bl 

End point drawing colour 


Comments 

GsGLINE is the structure that holds information necessary for drawing gradation straight 
lines. It is the same as forGsLINE except that drawing colour specification can be 
separately set at the start point and end point. 



GsBOXF 


Rectangle handler 


Structure 


struct GsBOXF { 


unsigned long attribute, 
short x, y; 

unsigned short w, h; 
unsigned char r, g, b; 


Members 


attribute Attribute 

28-29: Semi-transparency rate 


0 : 

1 : 

2 : 

3: 


0.5 x Back + 0.5 x Forward 

1.0 x Back + 1.0 x Forward 

1.0 x Back - 1.0 x Forward 

1.0 x Back + 0.25 x Forward 


30: Semi-transparency ON OFF 

0: Semi-transparency OFF 

1: Semi-transparency ON 

3 1 : Display ON OFF 

0: Display 

1: No display 




Comments 


x, y 

Display position (top left-hand point) 

x, y 

Size of rectangle (width, height) 

r, g, b 

Drawing colour 


GsBOXF is the structure that holds information necessary for rectangles painted by single 
colours. TheGsSortBoxFillQ function is used to registeiGsBOXF in the ordering table. 



ResetGraph 


Format 


Arguments 


Comments 


Return Value 


Initialises graphics system 


int ResetGraph ( 
int mode 
) 


mode Set mode 

0: All reset. The drawing environment and display 

environment are initialised. 

1 : The current drawing is cancelled and the command queue 

is flushed. 


It resets the graphics system with the mode that is specified bymode 


None 




SetDispMask 


Sets display mask 


Format 

void SetDispMask( 
int mask 
) 


Arguments 

mask 


0: Display is not carried out in ‘Display’. 

1: Display is carried out in ‘Display’. 


Comments 

It allows display to ‘Display’ 


Return Value 


None 




PutDrawEnv 


Sets drawing environment 


Format 

DRAWENV TutDrawEnvt 
DRAWENV ’fenv 
) 

Arguments 

env Drawing environment 


Comments 

Sets the basic parameters relating to drawing, e.g. drawing offset and drawing clip area. 


Return Value 

Top address of env 


Notes 

The drawing environment specified byPutDrawEnvQ is valid until PutDrawEnv() is 
executed or GsSwapDispBuff() is called. 

See Also 

—=— GsSwapDispBuffQ, DRAWENV 




PutDispEnv 


Sets display environment 


Format 

DISPENV H PutDispEnv( 
DISPENV t'nv 
) 


Arguments 

env 


Display environment 


Comments 

PutDispEnv sets the display environment. The display environment is immediately 
executed at the point in time when the function is called. 


Return Value 

Top address of env 


Notes 

The drawing environment specified byPutDispEnv() is valid until PutDispEnv() is 
executed or GsSwapDispBuffQ is called. 


See Also 


GsSwapDispBuffQ, DISPENV 




Loadlmage 


Transmits data to frame buffer 


Format 

int Loadlmage ( 
RECT *recp, 
u_long *p 
) 


Arguments 

recp Transmission destination rectangular area 

p Transmission source main memory address 


Comments 


Loadlmage transmits data below the addressp to the rectangular area of the frame buffer 
specified by recp. 


Return Value 

Queue number 


Notes 

Actual completion of the transmission needs to be identified byDrawSyncQ because it is a 
non-blocking function. 

The transmission area is not affected by the drawing environment (clip and offset). 

The transmission area needs to fit into the area in which drawing is possible (0,0) - 
(1023,511). 




St or el mage 


Transmits data from frame buffer 


Format 

int StoreImage( 
RECT *recp, 
u_long *p 
) 


Arguments 

recp Transmission source rectangular area 

p Transmission destination main memory address 


Comments 


Storelmage transmits the rectangular area of the frame buffer specified byecp to below 
the address p. 


Return Value 

Queue number 


Notes 

Actual completion of the transmission needs to be identified byDrawSyncQ because it is a 
non-blocking function. 

The transmission area is not affected by the drawing environment (clip and offset). 

The transmission area needs to fit into the area in which drawing is possible (0,0) - 
(1023,511). 




Movelmage 


Transmits data between frame buffer 


Format 

int MoveImage( 
RECT *recp, 
int x, 
int y 
) 


Transmission source rectangular area 

Transmission destination rectangular area top left-hand point 


Arguments 


recp 

x,y 


Comments 


Movelmage transmits the rectangular area of the frame buffer specified byecp to a 
rectangular area of the same size starting fromx,y. 


Return Value 

Queue number 


Notes 

Actual completion of the transmission needs to be identified byDrawSyncQ because it is a 
non-blocking function. 




The transmission area is not affected by the drawing environment (clip and offset). 

The transmission area needs to fit into the area in which drawing is possible (0,0) - 
(1023,5 1 1) for both the transmission source and transmission destination. 

The content of the transmission source is stored. Also, the function cannot be guaranteed 
if the areas of transmission source and transmission destination are overlapping, 



Clearlmage 


Frame buffer high speed painting 


Format 

int Clearlmage ( 
RECT *recp, 
u_char r, 
u_char g, 
u_char b 
) 


Arguments 

recp Painting rectangular area 

r, g, b Painting pixel value 


Comments 

Clearlmage paints the rectangular area of the frame buffer specified by ecp with the 
(r,g,b) brightness value. 


Return Value 

Queue number 


Notes 

Actual completion of the transmission needs to be identified byDrawSyncQ because it is a 
non-blocking function. 

The transmission area is not affected by the drawing environment (clip and offset). 




GetTPage 


Calculates primitive tpage member value 


Format 

u_short GetTPage ( 
int tp, 
int abr, 
int x, 
int y 
) 

Arguments 

tp Texture mode 

0: 4bitCLUT 

1: 8bitCLUT 

2: 16bitDirect 

abr Semi-transparency rate 

0: 0.5 x Back + 0.5 x Forward 

1: 1.0 x Back + 1.0 x Forward 

2: 1.0 x Back - 1.0 x Forward 

3: 1.0 x Back + 0.25 x Forward 

x, y 


Texture page address 




Comments 


GetTPage calculates the texture page ID and returns it. 


Return Value 

Texture page ID 


Notes 

The semi-transparency rate is also valid for polygons that do not carry out texture 
mapping. 

The texture page address is limited to multiples of 64 in the x direction and multiples of 
256 in the y direction. 



GetClut 


Format 


Arguments 


Comments 


Return Value 


Notes 


Calculates primitive clut member value 


ushort GetClut ( 
int x, 
int y 
) 


x, y 


CLUT frame buffer address 


GetClut calculates the texture CLUT ID and returns it. 


CLUT ID 


The CLUT address is limited to multiples of 16 in the x direction. 




DrawSync 


Waits for completion of all drawing 


Format 

int DrawSync( 
int mode 
) 


Arguments 

mode 


0: Waits for completion of all non-block functions registered in 

the queue. 

1 : The current rank number of the queue is checked and 

returned. 


Comments 

DrawSync waits for completion of the drawing. 


Return Value 


Actual queue rank number 




VSync 


Waits for vertical synchronisation 


Format 

int VSync( 
int mode 
) 


Arguments 

mode 


0: Blocking until vertical synchronisation occurs. 

1: The time elapsed from the point in time whenVSync() was previously 
called is returned in units of one horizontal synchronisation interval. 

n: (n>l) Counting from the point in time whenVSyncQ was previously 
called and blocking up to n times the occurrence of vertical 
synchronisation. 

n: (n<0) Absolute time from program activation is returned in vertical 
synchronisation interval units. 


Comments 

Vsync waits for vertical synchronisation. 

Return Value 

mode>=0 Time elapsed from point in time whenVSyncQ was previously 

called (horizontal return unit) 

mode<0 Time elapsed from program activation (vertical return unit) 




VSyncCallback 


Sets vertical synchronisation callback function 


Format 

int VSyncCallbacl( 
void (*func)() 

) 


Arguments 

fiinc 


Callback function 


Comments 

the function fiinc is called when vertical return section commence. 
Callback does not occur when 0 is specified infiinc. 


Return Value 

None 


Notes 

Subsequent drawing completion interruptions are masked withinfunc. Therefore, fiinc 
needs to return as soon as possible after completion of the necessary processing. 




FntLoad 


Format 


Arguments 


Comments 


Return Value 


Comments 


Notes 


Transmits font pattern 


void FntLoad( 
int tx, 
int ty 
) 


tx, ty 


Top left coordinate of the area of frame buffer that arranges the 
font patterns 


FntLoad transmits to the frame buffer the font pattern used for debugging. 


None 


FntLoad loads the basic font pattern (4bit texture 256x128) to the frame buffer, and 
initialises all print streams. 


FntLoad() must without fail be executed beforeFntOpen() and FntFlush(). 

The font area must not conflict with the frame buffer area used by the application. 




FntOpen 


Opens print stream 


Format 

int FntOpen) 
int x, 
int y, 
int w, 
int h, 
int isbg, 
int n 
) 


Display start positions 
Display area 

Background automatic clearance 

0: Background is cleared to (0,0,0) when displayed. 

1 : Background is not cleared to (0,0,0) when displayed. 
Number of letters 


Arguments 

x, y 
w, h 
isbg 

n 


Comments 

FntOpen opens the stream used for printing on screen. Thereafter, the largest n character 
string of letters can be printed in the rectangular area of the frame buffer (c,y)-(x+w, y+h) 
using the FntPrint() function. 

If 1 is specified in isbg, the background is cleared when a character string is drawn. 




Return Value 

Print stream ID 


Notes 

Up to 8 streams can be opened at the same time. 

Opened streams cannot be closed until the nextFntLoadQ is called 



FntPrint 


Format 


Arguments 


Comments 


Return Value 


Notes 


Output to print stream 


int FntPrint( 
int id, 
format, 


) 


id Print stream ID 

format Print format 


FntPrint sends the character string to the print stream by theprintfQ interface. 


Character string within the stream 


The actual display of the character string occurs whenFntFlush() is executed. 




FntFlush 


Format 


Arguments 


Comments 


Return Value 


Notes 


Draws print stream contents 


u_long *FntFlush( 
int id 
) 


id 


Print Stream ID 


FntFlush draws the print stream in the frame buffer. 


Temporary OT top pointer used in drawing 


After completion of drawing, the print stream contents are also flushed. 




KanjiFntOpen 


Opens print stream 


Format 

int KanjiFntOpen) 
int x, 
int y, 
int w, 
int h, 
int dx, 
int dy, 
int cx, 
int cy, 
int isbg, 
int n 
) 

Arguments 


x, y 

Display start positions 

w, h 

Display area 

dx,dy 

Kanji font pattern frame buffer address 

cx,cy 

Kanji clut frame buffer address 

isbg 

Background automatic clearance 


0: Background is cleared to (0,0,0) when displayed. 

1 : Background is not cleared to (0,0,0) when displayed, 
n Number of letters 




Comments 


KanjiFntOpen opens the stream used for printing on screen. Thereafter, the largest n 
character string can be printed in the rectangular area of the frame buffer(x,y)-(x+w,y+h) 
using the KanjiFntPrint() function. 

If 1 is specified inisbg, the background is cleared when a character string is drawn. 


Return Value 

Print stream ID 


Notes 

Up to 8 streams can be opened at the same time. 

Opened streams cannot be closed until the nextKanjiFntLoad() is called. 

The Kanji font area must not conflict with the frame buffer area used by the application. 



KanjiFntClose 


Closes print stream 


Format 


int KanjiFntClose( void ) 


Arguments 

None 


Comments 

This function closes all the streams currently openans are used by KanjiFntPrint() and 
initialize the state. 


Return Value 

None 


Notes 

Since KanjiFntClose() onlyinitializes the internal state, this function operations even 
when there is no stream. 




KanjiFntPrint 


Outputs to print stream 


Format 

int KanjiFntPrint( 

int id, 

format, 

) 


Arguments 

id Print stream ID 

format Print format 


Comments 

KanjiFntPrint sends the SHIFT-JIS full-width character string to the print stream by the 
printf() interface. 


Return Value 

Character string within the stream 


Notes 

The Kanji code must be SHIFT-JIS. 

Full-width and half-width characters can be mixed in the character string, but they are all 
changed to full-width at the time of display. Half-width kana are not supported. The actual 
display of the character string occurs whenKanjiFntFlush() is executed. 




KanjiFntFlush 


Format 


Arguments 


Comments 


Return Value 


Notes 


Draws print stream contents 


u_l°ng *KanjiFntFlush ( 
int id 
) 


id 


Print Stream ID 


FntFlush draws the print stream contents in the frame buffer. 


Temporary OT top pointer used in drawing 


After completion of drawing, the print stream contents are also flushed. 




Krom2Tim 


Converts SHIFT-JIS character strings to 4 bit CLUT data 


Format 

int Krom2Tim( 
u_char *sjis, 
u_long *taddr, 
int dx, 
int dy, 
int cx, 
int cy, 
u_int fg, 
u int bg 
) 

Arguments 

sjis 
taddr 
dx, dy 
cx, cy 
fg, bg 


SHIFT-JIS Character String 
Data storage area 

px,y coordinates on pixel data VRAM 
x,y coordinates onclut data VRAM 
Character colour andbg colour 


Comments 

Krom2Tim converts the SHIFT-JIS character string to 4 bitsdut TIM data and returns to 
taddr. 




Return Value 

-1 is returned if an irregular code is transferred. 


Notes 

The Kanji code must be SHIFT-JIS. Full-width and half-width characters can be mixed in 
the character string , but they are all changed to full-width at the time of display. Flalf- 
width kana are not supported. 

For the area specified bytaddr, the size shown in the following formula must be secured 
in advance. 

128 x (character string specified bysjis) + 84(byte) 



Krom2Tim2 


Converts SHIFT-JIS character strings to 4 bit CLUT Tim data 


Format 

int Krom2Tim2( 
u_char *sjis, 
u_long *taddr, 
int dx, 
int dy, 
int cdx, 
int cdy, 
u_int fg, 
u_int bg 
) 


Arguments 


sjis 

SHIFT-JIS Character String 

taddr 

Starting address of the converted TIM data 

dx, dy 

Pixel data x,y coordinates on VRAM 

cx, cy 

Clut data x,y coordinates on VRAM 

% bg 

Front and background colour 


Comments 

Krom2Tim2 converts the SHIFT-JIS character string to 4 bitsdut TIM data and returns 
the starting address in taddr. This is user defined character support version of 
Krom2Tim. 




Return Value 


-1 is returned if an invalid code is transferred. 


Notes 

The Kanji code must be in SHIFT-JIS. Although both ZENKAKU (double byte) and 
F1ANKAKU (single byte) can be mixedwitha string, all of them will not be converted to 
ZENKAKU. Please notethant HANKAKU KANA is not supported. 

Prior to calling this function, the area specified byfaddr' must be reserved with the size 
derived from the equation below. 

Num: number of characters specified bysjis. 

If (num<16) 

(32 * num + 16) * 4 (bytes) 

else 

(32 * 16* ((num-1/16 + 1) +16) * 4 (bytes) 



MulMatrixO 


Takes product of two matrices 


Format 

MATRIX* Mu IMatr ixO ( 

MATRIX *m0, 

MATRIX "Ini, 

MATRIX *m2 

) 

Arguments 

mO,ml Input matrix 

m2 Output matrix 


Comments 

MulMatrixO takes the product of the two matrices mO and ml. The value is stored inm2. 
The argument format is as follows. 
m0,ml,m2->m[i][j] : (1,3,12) 


Return Value 

m2 


Notes 


The rotation matrix is fragmented 




ApplyMatrix 


Multiplies vector by matrix 


Format 

VECTOR* ApplyMatrix( 
MATRIX *m, 

SVECTOR *v0, 

VECTOR *vl 

) 

Arguments 


m 

Input multiplication matrix 

vO 

Input short vector 

vl 

Output vector 


Comments 

ApplyMatrix multiplies from the right the short vectorvO by the matrix m and stores the 
result in the vector vl . 

The argument format is as follows. 
m->m[i][j] : (1,3,12) 

vO->vx,vy,vz :(1,15,0) 
vl->vx,vy,vz :(1 ,3 1 ,0) 


Return Value 

====== ~ vl 


Notes 


The rotation matrix is fragmented. 




ApplyMatrixSV 


Multiplies vector by matrix 


Format 

S VECTOR* App lyM atr ixS V( 
MATRIX *m, 

SVECTOR *v0, 

SVECTOR *vl 

) 

Arguments 


m 

Input multiplication matrix 

vO 

Input short vector 

vl 

Output short vector 


Comments 

ApplyMatrixSV multiplies from the right the short vectoivO by the matrix m and stores 
the result in the short vector vl. 

The argument format is as follows. 
n»m[i][j] : (1,3,12) 
vO->vx,vy,vz :(1,15,0) 
vl->vx,vy,vz :(1,15,0) 


Return Value 

_____ ^ 


Notes 


The rotation matrix is fragmented. 




ApplyMatrixLY 


Multiplies vector by matrix 


Format 

VECTOR* ApplyMatrixLV( 
MATRIX *m, 

VECTOR *v0, 

VECTOR *v 1 

) 

Arguments 


m 

Input multiplication matrix 

vO 

Input vector 

vl 

Output vector 


Comments 

ApplyMatrixSV multiplies from the right the short vectoivO by the matrix m and stores 
the result in the short vector vl. 

The argument format is as follows. 

n»m[i][j] : (1,3,12) 
vO->vx,vy,vz :(1,31,0) 
vl->vx,vy,vz :(1,31,0) 


Return Value 

_____ ^ 


Notes 


The rotation matrix is fragmented 




RotMatrix 


Searches for rotation matrix from rotation angle 


Format 

MATRIX* RotM atr ix ( 
MATRIX *m 
SVECTOR *r 
) 


Arguments 

m Output rotation matrix 

r Input rotation angle 

Comments 

RotMatrix supplies to matrix m the rotation matrix according to the rotation angle f- 
>vx,r->vy,r->vz). The rotation angle supplies 4096 as 360 1 , and 4096 is given as 1 .0 for 
the matrix component. 

The matrix is an expansion of the following product. Using the GTEcoordinate 
conversion function, the vectors are multiplied from the right, thus the matrix rotates 
around the Z, Y and X axes in that order. 


'1 

0 

0 " 


cl 

0 

si 


"c2 

-s2 

0 " 

0 

cO 

-sO 

* 

0 

1 

0 

* 

s2 

c2 

0 

_0 

sO 

cO 


-si 

0 

cl 


_0 

0 

1 




Angle value 

cO=cos(r->vx), sO=sin(r->vx) 
cl=cos(r->vy), sl=sin(r->vy) 
c2=cos(r->vz), s2=sin(r->vz) 

The argument format is as follows. 

m->m[i][j] : (1,3,12) 

r->vx,vy,vz :( 1 ,3,12) (however 360 is 1.0) 

Return Value 

m 



RotMatrixX 


Searches for rotation matrix around the X Axis 


Format 

MATRIX* RotM atr ixX ( 
long r, 

MATRIX ’in 

) 

Arguments 

r Input rotation angle 

m Input and output rotation matrix 

Comments 

RotMatrixX supplies to matrix m the matrix multiplied by the rotation matrix around the 
X axis according to the rotation angler. The rotation angle supplies 4096 as 36(T, and 
4096 is given as 1 .0 for the matrix component. 

The matrix is as follows. 

"10 O' 

0 c -s * m 
_0 s c 

* 


c=cos(r), s=sin(r) 




The argument format is as follows. 


m->m[i][j] : (1,3,12) 
r:(l,3,12) (however 36CP is 1.0) 


Return Value 

m 



RotMatrixY 


Searches for rotation matrix around the Y Axis 


Format 

MATRIX* RotM atr ixY ( 
long r, 

MATRIX ’in 

) 


Arguments 

r Input rotation angle 

m Input and output rotation matrix 


Comments 

RotMatrixY supplies to matrix m the matrix multiplied by the rotation matrix around the 
Y axis according to the rotation angler. The rotation angle supplies 4096 as 360 9 , and 
4096 is given as 1 .0 for the matrix component. 

The matrix is as follows. 


c 0 
0 1 
s 0 


-s 


0 


* m 


* 


c=cos(r), s=sin(r) 




The argument format is as follows. 


m->m[i][j] : (1,3,12) 
r:(l,3,12)(however 360° is 1.0) 


Return Value 

m 



RotMatrixZ 


Searches for rotation matrix around the Z Axis 


Format 

MATRIX* RotMatrixZ ( 
long r, 

MATRIX ’in 

) 

Arguments 

r Input rotation angle 

m Input and output rotation matrix 


Comments 

RotMatrixZ supplies to matrix m the matrix multiplied by the rotation matrix around the 
Z axis according to the rotation angler. The rotation angle supplies 4096 as 360 9 , and 
4096 is given as 1 .0 for the matrix component. 

The matrix is as follows. 


C -s 
S C 
0 0 


0 

0 

1 


* m 


* 


c=cos(r), s=sin(r) 




The argument format is as follows. 


m->m[i][j] : (1,3,12) 
r:(l,3,12)(however 360° is 1.0) 


Return Value 

m 



TransMatrix 


Format 


Arguments 


Comments 


Return Value 


Supplies amount of translation 


MATRIX*TransMatrix( 
MATRIX %% 

VECTORS 

) 


m Output matrix 

v Input shift vector 


TransMatrix supplies to matrix m the amount of translation shown byv. 
The argument format is as follows. 
n»m[i][j] : (1,3,12) 
n»t[i]: (1,31,0) 
v->vx,vy,vz : (1,31,0) 


m 




ScaleMatrix 


Supplies scaling factor 


Format 

MATRIX*ScaleMatrix ( 

MATRIX S-n, 

VECTOR*v 

) 

Arguments 

m Output matrix 

v Input scale vector 

Comments 

ScaleMatrix supplies to matrix m the scaling factor shown byv. It is a fixed decimal point 
number with 4096 as 1.0 for the v component. 


a 00 

aOl 

a 02 




alO 

all 

al2 

,v = 

[sx 

sy 

a20 

a21 

a22_ 




a 00 

* sx 

aOl * 

sy 

a 02 

* sz 

alO 

* sx 

all * 

sy 

al2 

* sz 

_a20 

* sx 

a21 * 

sy 

a 22 

* sz 


then m= 




The argument format is as follows. 


m->m[i][j] : (1,3,12) 
v->vx,vy,vz : (1,19,12) 


Return Value 

m 



ScaleMatrixL 


Supplies scaling factor 


Format 

MATRIX* ScaleMatrixL ( 

MATRIX %% 

VECTOR*v 

) 

Arguments 

m Output matrix 

v Input scale vector 

Comments 

ScaleMatrixL supplies to matrixmthe scaling factor shown byv. It is a fixed decimal 
point number with 4096 as 1 .0 for the v component. 


a 00 

aOl 

a 02 

alO 

all 

al2 

a20 

a21 

a 22 


aOO * sx 

aOl * sy 

alO * sx 

al 1 * sy 

a20 * sx 

a21 * sy 


[sx sy sz] 


a02 * sz 
al2 * sz 
a22 * sz 


then m= 




The argument format is as follows. 


m->m[i][j] : (1,3,12) 
v->vx,vy,vz : (1,19,12) 


Return Value 

m 



TransposeMatrix 


Supplies rotation value matrix 


Format 

MATRIX* T r ansp oseM atr ix( 

MATRIX ^'nO* C 
MATRIX Sul 
) 

Arguments 

mO Input matrix 

ml Output matrix 

Comments 

TransposeMatrix supplies to ml the rotation value matrix of matrixmO. 
The argument format is as follows. 

mO->m[i][j] : (1,3,12) 
ml->m[i][j] : (1,3,12) 


Return Value 


ml 




Comp Matrix 


Carries out coordinate conversion synthesis 


Format 

MATRIX^ompMatrixt 
MATRIX S-nO, 

MATRIX %il, 

MATRIX %i2 

) 

Arguments 


mO 

Input matrix 

ml 

Input matrix 

m2 

Output matrix 


Comments 

CompMatrix carries out synthesis ofcoordinate conversion matrices including translation. 


[m2->m] = [mO->m] * [ml->m] 

(m2->t) = [mO->m] * (ml->t) + (mO->t) 


However the value of theml->t component must be within the range of I —2^,2^ 




The argument format is as follows. 
mO->m[i][j] : (1,3,12) 
mO->t[i]: (1,31,0) 
ml->m[i][j] : (1,3,12) 
ml->t[i]: (1,15,0) 
m2->m[i][j] : (1,3,12) 
m2->t[i]: (1,31,0) 


Return Value 

m2 


Notes 

The rotation matrix is fragmented. 



PushMatrix 


Format 


Arguments 


Comments 


Return Value 


Evacuates rotation matrix to stack 


void PushMatrix( void ) 


None 


PushMatrix evacuates the rotation matrix to the stack. The stack is up to 20 levels. 


None 




PopMatrix 


Format 


Arguments 


Comments 


Return Value 


Resets rotation matrix from stack 


void PopMatrix ( void ) 


None 


PopMatrix resets the rotation matrix from the stack. 


None 




gteMIMefunc 


Adds differential data array from multiplication of vertex data 

array by coefficient 


Format 

void gteMIMefunc( 
SVECTOR <btp, 
SVECTOR Mfp, 
long n, 
long p 
) 


Input/output vertex array 

Input differential array 

Input vertex (differential) data number 

Input MIMe weight (control) coefficient 


Arguments 

otp 

dip 

n 

P 


Comments 

gteMIMefunc is a subroutine which executes interpolation using the differential data array 
and the vertex data array used in the multiple interpolation (MIMe) operation, 
p is the fixed decimal point data of the decimal 12bit. 




This function executes at high speed the same operation as the following program, 
void gteMIMefunc(S VECTOR fttp, S VECTOR ’tlfp, longn, longp) 


for( i = 0; i < n; i++){ 

(otp+i)->x += ( (int)((dfp+i)->x) * p )»12; 
(otp+i)->y += ( (mt)((dfp+i)->y) *p )»12; 
(otp+i)->z += ( (int)((dfp+i)->z) * p )» 1 2 ; 


The argument fonnat is as follows. 

P : (1,19,12) 
otp, dfp optional 

Return Value 

None 



GsInitGraph 


Graphics system initialisation 


Format 

void GsInitGraph ( 
int x_res, 
int y_res, 
int inti, 
int dither, 
int vram 
) 


Arguments 

x_res Horizontal resolution (256/320/384/5 12/640) 

y_res Vertical resolution (240/480) 

inti Interlace display flag (bit 0) 

0: Non-interlace 
1 : Interlace 

Double buffer offset mode (bit 2) 

0: GTE offset 
1: GPU offset 

dither Whether or not dither when drawing 

0: OFF 
1: ON 

vram Frame buffer mode 

0: 16bit 


1: 24bit 




Comments 


GsInitGraph initialises the graphics system. 

The GPU setting is notified by the global variablesGsDISPENV andGsDRAWENV, so 
the program GPU setting can be confirmed and changed by referring tiGsDISPENV and 
GsDRAWENV. 

The double buffer offset mode decides whether the double buffer offset is executed by 
GTE or by GPU. It is easier to handle when executed by GPU because the double buffer 
offset value is not included in the packet. 

In the 24-bit mode, only image display is possible. Polygon drawing etc. is not possible. 
Because initialisation of the graphics system includesGsIDMATRIX and GsIDMATRIX2 
initialisation, none of the Gs * * * functions operate normally unlessGsInitGraph() has 
been called. 


Return Value 


None 



GsInit3D 


3D graphics system initialisation 


Format 


void GsInit3D ( void ) 


Arguments 

None 


Comments 

GsInit3D initialises the 3D graphics system within the library. 

3D graphics system needs to be initialised by this function first, so that 3D processing 
functions such as GsSetRefViewO, GsInitCoordinate2() and GsSortObject4() can be used. 

The following process is executed. 

(1) The screen origin is held in the screen centre. 

(2) The light source defaults to LIGHT_NORMAL. 

Return Value 

None 


Notes 

With this function, the graphics system must firstly beintialised by GsInitGraphQ. 


See Also 


GsInitGraph(), GsSetRefViewQ, GsInitCoordinate2(), GsSortObject4() 




GsDefDispBuff 


Double buffer definition 


Format 

void GsDefDispBuff ( 

int xO, 

int yO, 

int xl , 

int yl , 

) 

Arguments 

xO, yO Buffer 0 origin (top left-hand) coordinates 

xl, yl Buffer 1 origin (top left-hand) coordinates 


Comments 

GsDefDispBuff defines the double buffer. (cO, yO) and (xl,yl) are specified by the 
coordinate value within the frame buffer. In default, the buffer 0 becomes (0, 0) and buffer 
1 becomes (0,y_res). 

y_res is the vertical resolution specified byGsInitGraph(). The double buffer is cancelled 
when (xO, yO) and (xl, yl) have the same coordinate values. Switching the double buffer 
of the even number field and odd number field is automatically carried out if it is left in 
this mode when the interlace mode is specified. 

Double buffer switching is carried out by theGsSwapDispBuff() function. 

The double buffer is executed by GPU or GTE offset. GsInitGraphQ sets 




whether execution of offset is by GPU or by GTE. If the double buffer is executed using 
the GPU offset, the coordinate value is created in the coordinate system whose origin is 
the top left-hand point of the double buffer in the packet. On the other hand, if the double 
buffer is executed using the GTE offset, thecoordinate value is created in the coordinate 
system whose origin is the origin (top left-hand point) of the frame buffer in the packet. 

Return Value 

None 

See Also 

GsInitGraphQ, GsSwapDispBuffQ 



GsSwapDispBuff 


Double buffer switching 


Format 


void GsSwapDispBuff) void ) 


Arguments 

None 


Comments 

GsSwapDispBuff changes the display buffer and drawing buffer according to double 
buffer information that has been set byGsDefDispBuffQ. Execution is usually carried out 
immediately after vertical return section surge. 

Also, the following processes are executed within the function. 

(1) Display commencement address setting 

(2) Cancellation of blanking 

(3) Double buffer index setting 

(4) 2 dimensional clipping switched 

(5) GTE or GPU offset setting 

(6) Offset setting 

(7) PSDCNT increment 

The double buffer is executed by the offset. The third argument ofGsInitGraph() decides 
whether the offset is set by GTE or by GPU (jsOFSGPU orGsOFSGTE is specified). 




Return Value 

None 

Notes 

If GPU is drawing, this function does not operate smoothly and it needs to be called 
immediately after drawing completion has been confirmed byDrawSync(O) or after the 
drawing has been ended by ResetGraph(l ). 

See Also 

GsDefDispBuffQ 



GsGetActiveBuff 


Gets drawing buffer number 


Format 


int GsGetActiveBuff ( void ) 


Arguments 

None 


Comments 

GsGetActiveBuff gets the double buffer index (PSDIDX). The index value is either 0 or 1 . 
The frame buffer top 2 dimensional address of the double buffer origin (top left 
coordinate) is found by entering the index in the external variables PSDOFSX[ ] and 
PSDOFSY[ ]. 


Return Value 

The double buffer index (0 when buffer 0 and 1 when buffer 1 ) is returned. 


See Also 


PSDIDX 




G sSetDr a wBuffO ffset 


Drawing offset update 


Format 


void GsSetDrawBuffOffset( void ) 


Arguments 

None 


Comments 

GsSetDrawBuffOffset updates the offset for drawing. The set value is represented in the 
global conversion POSITION. 

This offset is relative within the double buffer, and the offset value is maintained even if 
the double buffer is switched. 

The setting of GTE or GPU is executed if this function is called. The third argument of 
GsInitGraph() decides whether the offset is executed by GTE or by GPUGsOFSGPU or 
GsOFSGTE is specified). 


Return Value 

None 


Notes 

This function does not operate smoothly if GPU is drawing, and it needs to be called 
immediately after completion of drawing has been confirmed b)DrawSync(O) or after 
drawing has been ended by ResetGraph(l ). 

See Also 


GsSetOrignQ, GsSetOffset(), POSITION 




GsSetOffset 


Offset setting 


Format 

void GsSetOffset ( 
int offx, 
int offy 
) 

Arguments 


offx 

Drawing offset X 

offy 

Drawing offset Y 


Comments 

GsSetOffset specifies the drawing offset. It is different froiiGsSetDrawBuffOffset() in 
that GsSetDrawBuffOffsetQ sets the value of the global variable POSITION, whereas 
GsSetOffsetQ sets the offset supplied by the argument. 

Also, the value set byGsSetOffset() is temporary and the offset values that are set on 
execution ofGsSwapDispBuff() andGsSetDrawBuffOffsetQ become invalid. On the other 
hand, the set values of GsSetDrawBuffOffset() are valid until changed b>GsSetOrigin(). 
The offset supplied by the argument is relative within the double buffer. In other words, 
the offset actually set is the base offset of the double buffer added to the offset supplied by 
the argument. 

The third argument ofGsInitGraphQ decides whether the offset is executed by GTE or by 
GPU (GsOFSGPU orGsOFSGTE is specified). 




Return Value 

None 

Notes 

This function does not operate smoothly if GPU is drawing, and it needs to be called 
immediately after completion of drawing has been confirmed b)DrawSync(O) or after 
drawing has been ended by ResetGraph(l ). 

See Also 

GsSetDrawBuffOffsetO 



G sSetDr a wBuffC lip 


Drawing clipping area update 


Format 


void GsSetDrawBuffClip( void ) 


Arguments 

None 


Comments 

GsSetDrawBuffClip updates the drawing clip. It actually represents the clip value set by 
GsSetClip2D(). The set value is valid until theGsSetDrawBuffClipO function is called 
once more by a different clip value. 

Moreover, this clip value is relative within the double buffer, and the position of the clip 
does not change even if the double buffer is switched. 


Return Value 

None 


Notes 

This function does not operate smoothly if GPU is drawing, and it needs to be called 
immediately after completion of drawing has been confirmed b)DrawSync(O) or after 
drawing has been ended by ResetGraph(l ). 


See Also 


GsSetClip2D(), GsSetClipO 




GsSetClip 


Drawing clipping area setting 


Format 

void GsSetClip ( 
RECT *clip 
) 


Arguments 

clip 


RECT structure for setting the clipping area 


Comments 

GSetClip sets the clip for drawing. The set value is valid until theGsSwapDispBuff() 
function is called next. It is different fromGsSetDrawBuffClipO in that the place where 
the clip area can be specified by the argument and the validity period of the set value are 
different. 

Moreover, this clip value is relative within the double buffer. 


Return Value 

None 


Notes 

This function does not operate smoothly if GPU is drawing, and it needs to be called 
immediately after completion of drawing has been confirmed b)DrawSync(O) or after 
drawing has been ended byResetGraph(l). 

See Also 


GsSetDrawBuffClipO 




GsGetTimlnfo 


Checks TIM format header 


Format 

void GsGetTimInfo( 
unsigned long *tim, 
GsIMAGE *im 
) 


TIM data top address 
Pointer to image structure 


Arguments 


tim 

im 


Comments 

TIM format information specified by the argumentim is stored in im. 

The top of the TIM data is the address that skipped the ID. In other words, it has an offset 
4 bytes forward from the top of the TIM file. 

For file format, please refer to the NetYaroze Members' Web site. 


Return Value 

None 


See Also 


GsIMAGE 




GsMapModelingData 


Maps TMD data to an actual address 


Format 

void GsMapModelingData( 
unsigned long *p 
) 


Arguments 

P 


Top address of TMD data 


Comments 

The offset address from the top of the TMD data is stored because at the time of TMD 
data creation it is uncertain where it is going to be loaded onto the memory. 

The GsMapModelingData() function converts this offset address into an actual address, 
and this conversion must be carried out first of all in order to use the TMD data. 

The TMD data top address is the one that skipped the ID. In other words, it has an offset 4 
bytes forward from the top of the TMD file. 

For file format, please refer to the NetYaroze Members' Web site. 


Return Value 

None 


Notes 

A flag stands in the TMD data converted to an actual address, so that no side effects will 
occur even ifGsMapModelingData() is called for a second time. 



GsLinkObject4 


Format 


Arguments 


Comments 


Return Value 


Notes 


See Also 


Links object and TMD data 


void GsLinkObject4( 
unsigned long *tmd, 
GsDOBJ2 *obj_base, 
unsigned long n 
) 


tmd Top address of the linking TMD data 

obj base Array of the object structure to be linked 

n Index of the linking object 


GsLinkObject4 links the TMD data (nth) object with the object structure of GsDOBJ2, so 
that TMD 3D objects can be handled by GsDOBJ2. 


None 


Objects linked by GsLinkObject4() can be registered in OT by GsSortObject4(). 


GsSortObject4(), GsDOBJ2 




GsSetRefView2 


Viewpoint position setting 


Format 

int GsSetRefView2( 
GsRVIEW2 *pv 
) 


Arguments 

pv 


Viewpoint position infonnation (viewpoint: steady viewpoint 
type) 


Comments 


GsSetRefView2 calculates the WSMATRIX (World Screen Matrix) from the viewpoint 
information. If the viewpoint does not move, the WSMATRIX does not change and does 
not need to be called each frame. However, when the viewpoint moves, changes are not 
represented unless the WSMATRIX is called each frame. 

When super of the GsRVIEW2 member is set outside WORLD, even if other parameters 
are not changed, GsSetRefView2() needs to be called each frame becausethe viewpoint 
moves if the parent coordinate system parameters change. 


Return Value 

0 is returned when viewpoint setting is successful, 1 when it fails. 


See Also 


GsRVIEW2,GsWSMATRIX, GsSetView2() 




GsSetView2 


Viewpoint setting 


Format 

int GsSetView2( 

GsVIEW2 *pv 

) 

Arguments 

pv Viewpoint position information (matrix type) 


Comments 

GsSetView2 directly sets the WSMATRIX (World Screen Matrix). If the viewpoint is 
moved, errors can arise due to inaccuracy in the process that searches WSMATRIX from 
the viewpoint steady viewpoint using GsSetRefView2(), and so it is advantageous to use 
GsSetView2(). 

When super of the GsVIEW2 member is set outside WORLD, GsSetRefView2() needs to 
be called each frame even if other parameters are not changed. This is becausethe 
viewpoint movesunless the parent coordinate system parameters change. 

The screen aspect ratio is regulated automatically if GsIDMATRIX2 is used in the basic 
matrix. 


Return Value 

0 is returned if setting is successful, 1 if it fails. 


See Also 


GsVIEW2,GsWSMATRIX, GsSetRefView2() 




GsSetProjection 


Projection plane position setting 


Format 

void GsSetProjection ( 
unsigned short h 
) 


Arguments 

h Distance between viewpoint and projection plane (projection 

distance), 

default is 1000. 


Comments 

GsSetProjection regulates the field of view. 

The projection is the distance from the viewpoint to the projection plane. 

The size of the projection plane is set by theGsInitGraph() arguments xres, yres. The field 
of view narrows if the projection distance is enlarged and expands if it is reduced, because 
the size of the projection plane is fixed according to the resolution. 

Be careful, because sometimes aspect ration is not 1 to 1 , depending on the resolution. In 
this case, the scale of Y coordinates is made 1/2 and the aspect ratio is adjusted. 


Resolution 

640x480 

640x240 

320x240 

Aspect ratio 

1:1 

2:1 

1:1 


Return Value 


None 





GsSetFlatLight 


Parallel light source setting 


Format 

void GsSetFlatLight ( 
unsigned short id, 
GsFLIGHT “It 
) 


Light source number (0,1,2) 
Light source information 


Arguments 


id 

It 


Comments 

GsSetFlatLight sets the parallel light source. The light source can be set up to three {d = 

0 , 1 , 2 ). 

Light source information is given by theGsF_LIGHT structure. 


Return Value 

None 


Notes 

Even if the contents of theGsFLIGHT structure are rewritten, the setting is not 
represented unless this function is called. 


See Also 


GsF LIGHT, GsSetAmbient() 




GsSetLightMode 


Light source mode setting 


Format 

void GsSetLightMode( 
unsigned short mode 
) 


Arguments 

mode 


Light source mode (0—1) 

0: normal lighting 
1 : normal lighting fog ON 


Comments 

GsSetLightMode sets the light source mode. 

The light source calculation method can also be set by the status bit (attribute) of each 
object (GsDOBJ2). Setting by the status bit is used in precedence to the status setting. 


Return Value 


None 




GsSetFogParam 


Fog parameter setting 


Format 

void GsSetFogParam ( 
GsFOGPARAM Togparam 
) 


Arguments 

fogparam 


Pointer to fog parameter structure 


Comments 

GsSetFogParam carries out fog parameter setting. Fog is only effective if the light mode is 

1 . 


Return Value 

None 


See Also 


GsFOGPARAM, 


GsSetLightMode() 




GsSetAmbient 


Format 


Arguments 


Comments 


Return Value 


See also 


Ambient colour setting 


void GsSetAmbient( 
unsigned short r, 
unsigned short g, 
unsigned short b 
) 


r, g, b 


RGB value of the ambient colour (0~4095) 


GsSetAmbient sets ambience (ambient light). Setting is carried out in each ofr, g and b 
according to what fraction of unlit parts there are to lit parts. 1/1 becomes 4096 and 1/8 
becomes 4096/8. 


None 


GsSetFlatLightQ 




GsInitCoordinate2 


Format 


Arguments 


Comments 


Return Value 


See Also 


Local coordinate system initialisation 


void GsInitCoordinate2( 
GsCOORDINATE2 “Super, 
GsCOORDINATE2 “base 
) 


super Pointer to parent coordinate system 

base Pointer to (initialising) coordinate system 


GsInitCoordinate2 initialises the localcoordinate system. Initialisation ofbase- >coord is 
by the unit matrix, and base- >super by the coordinate system specified by the argument. 


None 


GsCOORDINATE2 




GsGetLw 


Format 

Arguments 

Comments 


Return Value 
See Also 


Calculates local world matrix 


void GsGetLw ( 
GsCOORDINATE2 toord, 
MATRIX %i 
) 


coord Pointer to local coordinate system 

m Pointer to matrix 


GsGetLw calculates the local world perspective conversion matrix froncoord of the 
matrix type coordinate system GsCOORDINATE2 specified by the argument and stores 
the result in the MATRIX type structurem. 

Also, the calculation result of each node of the hierarchicaleoordinate system is held in 
order to increase speed, and calculation up to nodes that are not changed is omitted even 
when the GsGetLw() function is next called. 

This is controlled by the GsCOORDINATE2 flag ( 1 is substituted for the 
GsCOORDINATE2 flag after calculation). However, even when 1 is substituted for the 
flag, note that calculation will be carried out if the parent node has been changed. 

None 


GsGetLwsQ, GsSetLightMatrixQ 




GsGetLs 


Calculates local screen matrix 


Format 

void GsGetLs ( 
GsCOORDINATE2 toord, 
MATRIX 
) 


Arguments 

coord Pointer to local coordinate system 

m Pointer to matrix 


Comments 

GsGetLs calculates the perspective conversion matrix of the local screen froneoord of 
the matrix type coordinate system GsCOORDINATE2 specified by the argument, and the 
result is stored in the MATRIX type structurem. 

Also, the calculated result of each node of the hierarchicalcoordinate system is held in 
order to increase speed, and calculation up to nodes that are not changed is omitted even 
when the GsGetLw() function is next called. 

This is controlled by the GsCOORDINATE2 flag ( 1 is substituted for the 
GsCOORDINATE2 flag after calculation). However, even when 1 is substituted for the 
flag, note that calculation will be carried out if the parent node has been changed. 


Return Value 


None 




See Also 


GsSetLsMatrixQ 



GsGetLws 


Calculates both local world and local screen matrices 


Format 

void GsGetLws ( 
GsCOORDINATE2 toord2 
MATRIX «lw, 

MATRIX ^s 

) 


Arguments 

coord2 Pointer to local coordinate system 

lw Pointer to local world coordinate system 

Is Pointer to local screen coordinate system 


Comments 

GsGetLws calculates both the local worldcoordinates and the local screen coordinates at 
the same time from the localcoordinate systemcoord2, and stores them in lwand Is. It is 
faster than continuously callingGsGetLw() andGsGetLs(). 

The local world matrix must be specified if light source calculation is carried out at the 
time of execution, but in this case it is faster to search once withGsGetLwsQ. 


Return Value 

None 


See Also 


GsGetLsQ, GsGetWsQ 




GsScaleScreen 


Scales screen coordinate system 


Format 

voidGsScaleScreen( 

SVECTOR *scale 

) 


Arguments 

scale The scale factor (12bit fixed decimal point format) 

GsScaleScreen sets the scale factor for the original screen 
coordinate system normally set by GsSetView2() and 
GsSetRefView2(). 

By entering ONE forvx, vy andvz , it returns to the original. 


Comments 

GsScaleScreen carries out scaling of the screencoordinate system with respect to the 
world coordinate system. 

Problems such as the closeness of Far Clip occur because the screencoordinate system is 
only 16bit whereas the world coordinate system has a 32bit space. GsScaleScreen() is a 
function that resolves this problem, carries out scaling of the screencoordinates and 
covers a wider area for the worldcoordinates. 

For example, the screencoordinate system expands to a 17bit equivalent size when 
ONE/2 is specified in (vx,vy,vz). However, as precision is 16bit, the bottom 1 bit is 
invalid. 

At this time, screen coordinate systems with different scales should not be registered in 
OT with the same scale. For example, registration must be carried out by shifting to one 
extra bit, in order to register objects, calculated with the screencoordinate system of the 




normal scaling, to the OT that registered the objects that were half the scale of the screen 
coordinate system. 

Return Value 

None 



GsSetLsMatrix 


Sets local screen matrix 


Format 

void GsSetLsMatrix( 
MATRIX %ip 
) 


Arguments 

mp 


Local screen matrix to be set 


Comments 

GsSetLsMatrix sets the local screen matrix in GTE. 

If perspective conversion process is carried out using GTE, the local screen matrix needs 
to be pre-set in GTE. 

Because the GsSortObject4() function performs perspective conversion using GTE, 
GetLsMatrix() needs to be called beforehand 


Return Value 

None 


See Also 


GsSortObject4(), GsGetLsQ 




GsSetLightMatrix 


Sets light matrix 


Format 

void GsSetLightMatrix( 
MATRIX %ip 
) 


Arguments 

mp 


Local screen light matrix to be set 


Comments 

GsSetLightMatrix multiplies the matrix of three light source vectors and the local screen 
light matrix mp supplied by the argument, and sets in GTE. 

Depending on the type of modelling data to be handled, the GsSortObject4() function may 
perform light source calculation at the time of execution. In this case too, the light matrix 
needs to be pre-set using GsSetLightMatrix(). 

The matrix set as the GsSetLightMatrixQ argument is normally the local world matrix. 


Return Value 

None 


See Also 


GsSortObject4(), GsGetLw() 




GsClearOt 


OT initialisation 


Format 

void GsClearOt ( 
unsigned short offset, 
unsigned short point, 
GsOT *otp 
) 


Arguments 


offset 

Ordering table offset value 

point 

Ordering table representative value Z 

otp 

Pointer to ordering table 


Comments 

GsClearOT initialises the ordering table displayed byotp. offset is the Z value at the top 
of that ordering table, and point is the Z value referred to when inserting that ordering 
table into another ordering table. 

Also, the length of OT must be specified in advance in order to confirm the size to be 
cleared. 


Return Value 

None 


See Also 


GsOT, GsDrawOtf) 




GsDrawOt 


Format 


Arguments 


Comments 


Notes 


Return Value 


See Also 


Execution of drawing command allocated to OT 


void GsDrawOt ( 
GsOT *otp 
) 


otp 


Pointer to OT 


GsDrawOt starts execution of the drawing command registered in OT displayed 
by otp. 

GsDrawOtQ immediately returns because the drawing process is carried out in the 
background. 

If GPU is drawing, this function does not operate smoothly and it needs to be called 
immediately after drawing completion has been confirmed byDrawSync(O) or after 
drawing has been ended byResetGraph(l). 


None 


GsOT, GsClearOtQ 




GsSortObject4 


Allocates object to ordering table 


Format 

void GsSortObject4( 
GsDOBJ2 *objp, 
GsOT *otp, 
long shift, 
u_long *scratch 
) 


Arguments 

objp 

otp 

shift 

scratch 


Pointer to object 
Pointer to OT 

How many bits the value of Z is shifted to the right at the time 
of allocation to OT 
Specifies scratchpad address 


Comments 

GsSortObject4 carries out perspective conversion and light source calculation for 3D 
objects to be handled by GsDOBJ2, and generates the drawing command in the packet 
area specified by GsSetWorkBase(). Next, it Z sorts the generated drawing command and 
allocates it to OT displayed byotp. 

The precision of Z can be adjusted by the value ofshift. The maximum value of the 
ordering table size (resolution) is Mbit. However, if for example it is Mbit, then the value 
of shift is 2 (=14 - 12). At this time take care not to go over the area of the ordering table, 
scratch is used as work when automatic division is carried out. 




In order to validate the division by attribute which is the member ofcbjp, OR is carried 
out by GsDIV5, which is the member of macro GsDIVlobjp defined by libps.h. One 
polygon 

is divided into 4 sections of 2x2 at the time of GsDIVl and into 1024 sections of 32x32 at 
the time of GsDIV5. 

Also, scratchpad is cache memory and 256 words are packaged from 0xlf800000. 

Return Value 

None 

See Also 

~ GsDOBJ2, GsSetWorkBase() 



GsSetWorkBase 


Sets drawing command storage address 


Format 

void GsSetW orkBase( 

PACKET ’tase addr 

) 

Arguments 

base addr Address that stores the drawing command 

Comments 

GsSetWorkBase sets the memory address that stores the drawing primitives generated by 
such functions as GsSortObject4() andGsSortSprite(). 

At the start of the process of each frame, it must be set in the top address of the packet 
area secured by the user. 

Return Value 

None 

See Also 

GsSortObject4(), GsSortSpriteQ, GsSortFastSpriteQ, GsOUT PACKET P 




GsGetW orkBase 


Gets current drawing command storage address 


Format 

PACKET !| GsGetWorkBase( void ) 

Arguments 

None 

Comments 

GsGetWorkBase gets the current drawing primitive packet address 
The top address of the unused area can be got. 

Return Value 

The address that creates the next drawing primitive packet 

See Also 

= " ' GsSetWorkBase(), GsOUT PACKET P 




GsSortClear 


Registers drawing clear command in OT 


Format 

void GsSortClear ( 
unsigned char r, 
unsigned char g, 
unsigned char b, 
GsOT *otp 
) 


Arguments 

r, g, b Background colour RGB Value 

otp Pointer to OT 


Comments 

GsSortClear sets the drawing clear command at the top of OT displayed byitp. 


Return Value 

None 


Notes 

GsSortClear only registers the clear command in the ordering table, and is not executed 
unless the drawing is started by the GsDrawOtQ function. 




GsSortSprite 


Registers sprite in OT 


Format 

void GsSortSprite( 
GsSPRITE *sp, 
GsOT *otp, 
unsigned short pri 
) 

Arguments 


sp 

Pointer to sprite 

otp 

Pointer to OT 

pri 

Position in OT 


Comments 

GsSortSprite allocates the sprite displayed bysp to the ordering table displayed byotp. 

The parameters of sprite display positions, etc. are all supplied by thesp members, 
pri is the priority order on the sprite ordering table. The highest value is 0 and the lowest 
value depends on the size of the ordering table. If a numerical value of the size of the 
ordering table or more is specified, it is clipped to the maximum value got by the ordering 
table. 


Return Value 

None 


See Also 


GsOT, GsSPRITE, GsSortFastSprite() 




GsSortFastSprite 


Registers sprite in OT 


Format 

void GsSortFastSprite( 
GsSPRITE %p, 

GsOT *otp, 
unsigned short pri 
) 


Arguments 


sp 

Pointer to sprite 

otp 

Pointer to OT 

pri 

Position in OT 


Comments 

GsSortSprite allocates the sprite displayed bysp to the ordering table displayed byotp. 

The parameters of sprite display positions, etc. are all supplied by thesp members, 
pri is the priority order on the sprite ordering table. The highest value is 0 and the lowest 
value depends on the size of the ordering table. If a numerical value of the size of the 
ordering table or more is specified, it is clipped to the maximum value got by the ordering 
table. 

In comparison with theGsSortSprite() function, GsSortFastSprite() is processed at high 
speed, although the scaling rotation function cannot be used. At this time, the value of the 
sprite structure members, mx, my, scalex, scaley and rotate are disregarded. 




Return Value 

None 

See Also 

GsSortSprite(),GsSPRITE 



GsInitFixBgl6 


Initialises high-speed BG working area 


Format 

void GsInitFixBgl6 ( 
GsBG *bg, 
unsigned long *work 
) 


Arguments 

bg Pointer to GsBG 

work Pointer to working area (primitive area) 

Comments 

GsInitFixBgl6 initialises the working area used by the GsSortFixBgl6 () function. The 
size of the necessary array varies according to the screen resolution. The size can be found 
by the following formula (unit is long). 

Size = (((ScreenW/CellW+l)*(ScreenFl/CellH+l+l)*6+4)*2+2) 

ScreenFl: Screen height vertical dot number (240/480) 

ScreenW: Screen height horizontal dot number (256/320/384/512/640) 

CellH: Cell height (pixel number) 

CellW: Cell width (pixel number) 

GsInitFixBgl6() should only be executed once, and does not need to be executed every 
frame. 


Return Value 


None 




See Also 


GsSortFixBgl6() 



GsSortFixBgl6 


Registers high-speed BG to OT 


Format 


Arguments 


void GsSortFixBgl6( 


GsBG *bg, 


unsigned long *worl^ 


GsOT *otp, 


unsigned short pri 


) 


bg 

Pointer to GsBG 

work 

Pointer to working area (primitive area) 

otp 

Pointer to OT 

pri 

Position in OT 


Comments 

GsSortFixBgl6 carries out BG data registration processing to the ordering table. 

BG rotation/scaling/reduction not possible. 

Cell size fixed (16x16). 

Texture pattern colour mode 4bit/8bit only. 

Map size is optional. 

Scrolling possible ( 1 pixel unit) 

Full screen only 

This function needs working area for storing the drawing primitives. The working area is 
prepared as an unsigned long type array, and initialisation by GsInitFixBgl6() needs to be 
carried out in advance. 




Packet Area (the area set byGsSetWorkBaseQ) is not used. 


Return Value 

None 

See Also 

GsInitFixBgl6() 



GsSortLine 


Registers straight lines to OT 


Format 

void GsSortLine( 
GsLINE Ip, 

GsOT *otp, 
unsigned short pri 
) 

Arguments 


lp 

Pointer to GsLINE 

otp 

Pointer to OT 

pri 

Position in OT 


Comments 

GsSortLine allocates straight lines that are displayed bylp to ordering table displayed by 
otp. 

Single colour straight lines are registered in OT byGsSortLine(). 


Return Value 

None 


See Also 


GsSortGLineQ 




GsSortGLine 


Registers straight lines to OT 


Format 

void GsSortGLine( 
GsGLINE Ip, 

GsOT *otp, 
unsigned short pri 
) 

Arguments 


lp 

Pointer to GsGLINE 

otp 

Pointer to OT 

pri 

Position in OT 


Comments 

GsSortGLine allocates straight lines that are displayed bylp in the ordering table 
displayed by otp. 

Straight lines with gradation are registered in OT byGsSortGLineQ. 


Return Value 

None 


See Also 


GsSortLineQ 




GsSortBoxFill 


Format 


Arguments 


Comments 


Return Value 


Registers rectangles to OT 


void GsSortBoxF ill ( 
GsBOXF *bp, 

GsOT *otp, 
unsigned short pri, 

) 


bp 

Pointer to GsBOXF 

otp 

Pointer to OT 

pri 

Position in OT 


GsSortBoxFill allocates rectangles displayed bybp to ordering table displayed byotp. 


None 




GsSortOt 


Allocates OT to another OT 


Format 

GsOT *GsSortOt ( 

GsOT *ot_src, 

GsOT *ot_dest 

) 

Arguments 

ot_src Pointer to assigned source OT 

ot_dest Pointer to assigned destination OT 


Comments 

GsSortOt assigns the OT displayed byot_src to ot_dest 

The OTZ value used at this time is the representative value in theot_src point field. 
The integrated OT is assigned to ot dest. 


Return Value 

Pointer to integrated OT 


See Also 


GsOT 




GsSetClip2D 


2 dimensional clipping setting 


Format 

void GsSetClip2D( 
RECT *rectp 
) 


Arguments 

rectp 


Clip area 


Comments 

GsSetClip2D sets the area displayed byrectp as the clipping area. 

This setting is not influenced by the double buffer, and so once it is set, the same area is 
automatically clipped even if the double buffer is switched. 

GsSetDrawBuffClipO needs to be called in order to validate this setting immediately 
afterwards. If GsSetDrawBuffClipO is not called, the setting becomes valid from the next 
frame. 

Return Value 


None 




GsSetOrign 


Screen origin position setting 


Format 

void GsSetOrign ( 
int x, 
int y 
) 


Arguments 

x Screen origin position X 

y Screen origin position Y 


Comments 

GsSetOrign specifies the drawing offset. 

The offset value set byGsSetOffset() is temporary and whereas the offset set when 
GsSwapDispBuff() orGsSetDrawBuffOffset() is called becomes invalid, the offset value 
set by GsSetOrignQ is valid until next changed byGsSetOrign(). 

The offset supplied by the argument is relative within the double buffer. In other words, 
the offset actually set is the offset supplied by the argument added to the offset of the 
double buffer base. In reality, it is set byoffx and offy of the global variable POSITION. 

Notes 

The third argument ofGsInitGraphQ decides whether the offset is executed by GTE or by 
GPU (GsOFSGPU orGsOFSGTE is specified). 


Return Value 


None 




GsIncFrame 


Updates frame ID 


Format 


GsIncFrame() 


Arguments 

None 


Comments 

GsIncFrame is the macro called insideGsSwapDispBuff(). It applies one increment to 
PSDCNT. Although PSDCNT is 32bit, it does not become 0 even if it is recycled, and it 
starts from 1 . 

PSDCNT is referred to when the validity of the matrix cache is determined bjGsGetLwO, 
GsGetLs() andGsGetLws(). 

If the double buffer is switched without usingGsSwapDispBuff() andGsGetLw(), 
GsGetLs() and GsGetLws( ) are used, this macro needs to be called every time the double 
buffer is switched. 


See Also 


PSDCNT, GsGetLwQ, GsGetLsQ, GsGetLwsQ, GsSwapDispBuffQ 




Table: Graphics External Variables 


Global 

Type 

Description 

CLIP2 

RECT 

2 dimensional clipping area 

PSDOFSX [2] 

unsigned short 

Double buffer base point (X coordinate) 
Set byGsDefDispbuffQ 

PSDOFSY [2] 

unsigned short 

Double buffer base point (Y coordinate) 
Set byGsDefDispbuffQ 

PSDIDX 

unsigned short 

Double buffer index 

PSDCNT 

unsigned long 

Number incremented by frame switch 

POSITION 

GsPOSITION 

2 dimensional offset 

GsDRAWENV 

DRAWENV 

Drawing Environment 

GsDISPENV 

DISPENV 

Display Environment 

GsLSMATRIX 

MATRIX 

Local screen matrix 
Set byGsSetLsO 

GsWSMATRIX 

MATRIX 

World screen matrix 
Set byGsSetRefView(), etc. 

GsLIGHTMODE 

int 

Default light mode 

GsLIGHTWSMATRIX 

MATRIX 

Light matrix 

Set byGsSetFlatLight() 

GsIDMATRIX 

MATRIX 

Unit matrix 

GsIDMATRIX2 

MATRIX 

Unit matrix (including aspect conversion) 

GsOUT PACKET P 

unsigned long 

Pointer holding top of packet area 
Set byGsSetWorkBase() 

GsLMODE 

unsigned long 

Attribute decoding result (light mode) 

GsLIGNR 

unsigned long 

Attribute decoding result (light disregarded) 

GsLIOFF 

unsigned long 

Attribute decoding result (without shading) 

GsNDIV 

unsigned long 

Attribute decoding result (division number) 

GsTON 

unsigned long 

Attribute decoding result (semi-transparency) 

GsDISPON 

unsigned long 

Attribute decoding result (display/ no display 








































































Sound Functions 




SndVolume 





Volume 

Structure 

struct SndVolume { 

unsigned short left; 



}; 

unsigned short right; 


Members 

~ left 

L channel volume value 



right 

R channel volume value 





SsVabTransfer 


Recognises and transmits sound source data 


Format 

short SsVabTransfer( 
unsigned char vhaddr, 
unsigned char vb_addr, 
short vabid, 
short i_flag 
) 

Arguments 


vhaddr 

VH data top address 

vb_addr 

VB data top address 

vabid 

VAB identification number 

i_flag 

Fixed at 1 


Comments 

SsVabTransfer recognises the sound source header list (VH data) specified byvh_addr, 
and transmits the sound source data (VB data) specified byvb_addrto the SPU sound 
buffer. It specifies the VAB identification number irtvabid. It searches and allocates an 
available VAB identification number (0 - 15) whenvabidis -1. 


Return Value 

VAB identification number 

In the case of failure, the following values are returned according to the cause. 


-1 


VAB ID cannot be assigned or VH abnormality 




-2 

-3 or below 


See Also 


SsVabCloseQ 


VB abnormality 
Other abnormalities 



SsVabClose 


Format 


Arguments 


Comments 


Return Value 


See Also 


Closes VAB data 


void SsVabClose( 
short vab id 
) 


vab id 


VAB data id 


SsVabClose closes VAB data that holdsvab id 


None 


SsVabTransferQ 




SsSeqOpen 


Opens SEQ data 


Format 

short SsSeqOpen ( 
unsigned long* addr, 
short vabid 
) 


Arguments 

addr SEQ data main memory top address 

vab id VAB id 


Comments 

SsSeqOpen analyses the SEQ data in the main memory, and returns the SEQ access 
number. 

A maximum of 32SEQ data can be opened at the same time and if more than that are 
opened, -1 becomes the return value. 


Return Value 

SEQ access number (the number to be used within the SEQ data access function and the 
number of the SEQ data control table held internally). 


See Also 


SsSeqClose() 




SsSeqClose 


Format 


Arguments 


Comments 


Return Value 


See Also 


Closes SEQ data 


void SsSeqClose( 
short seq_access_num 
) 


seq_access num SEQ access number 


SsSeqClose closes the SEQ data holding theseq acces numthat is no longer necessary. 


None 


SsSeqOpenQ 




SsSeqPlay 


SEQ data reading (musical performance) 


Format 

void SsSeqPlay( 
short seq_access_num 
char play_modq 
short l_count 
) 


Arguments 

seq_access num SEQ access number 

play_mode Perfomiance mode 

SSPLAYPAUSESwitches to pause state 
S SPLAY PLAY Performs immediately 
l_count Number of tune repetitions 


Comments 

According to theplay_modevalue, SsSeqPlay can select whether to begin reading 
(performing) the SEQ data immediately or switch to the pause state at the SEQ data top 
(tune top). At this time, it specifies the number of tune repetitions inl_count 
SSPLAY_INFINITY is specified if there is an infinite number of performances 


Return Value 

None 


See Also 


SsSeqPauseQ, SsPlayBackQ, SsSeqStopQ 




SsSeqPause 


Format 


Arguments 


Comments 


Return Value 


See Also 


Temporarily stops SEQ data reading (pause) 


void SsSeqPause( 
short seq_access_num 
) 


seq_access num SEQ access number 


SsSeqPause temporarily stops the reading (performance) of SEQ data holding 
seq_access_num 


None 


SsSeqPlayQ, SsSeqReplayQ 




SsSeqReplay 


Format 


Arguments 


Comments 


Return Value 


See Also 


Restarts SEQ data reading (replay) 


void SsSeqReplay! 
short seq_access_num 
) 


seq_access num SEQ access number 


SsSeqReplay restarts the reading of the SEQ data holdingseq_access_numthat has been 
temporarily suspended bySsSeqPause. 


None 


SsSeqPlayQ, SsSeqPauseQ 




SsSeqStop 


Format 


Arguments 


Comments 


Return Value 


See Also 


Stops SEQ data reading (stop) 


void SsSeqStop ( 
short seq_access_num 
) 


seq_access num SEQ access number 


SsSeqStop ends the reading (performance) of the SEQ data holdingeq_access_num 


None 


SsSeqPlayQ 




SsSeqSetVol 


Format 


Arguments 


Comments 


Return Value 


See Also 


SEQ volume setting 


void SsSeqSetVol( 
short seq_access_num 
short voll, 
short voir 
) 


seq_access num SEQ access number 

voll L channel main volume value 

voir R channel main volume value 


SsSeqSetVol sets the main volume of the tune holdingseq_access_numin sizes specified 
in the L and R channels respectively. 0 to 127 can be set. 


None 


SsSeqGetVolQ 




SsSeqGetVol 


Gets SEQ volume 


Format 

void SsSeqGetVol( 
short access_num 
short seqnum, 
short *voll, 
short *volr 
) 


Arguments 

access_num SEQ access number 

seq num Fixed at 0 

voll SEQ L volume value 

voir SEQ R volume value 


Comments 

SsSeqGetVol returns the current L and R volume values of SEQ toroll and voir 
respectively. 


Return Value 

None 


See Also 


SsSeqSetVolQ 




SsSeqSetNext 


Format 


Arguments 


Comments 


Return Value 


Next SEQ data specification 


void SsSeqSetNextf 
short seq_access_numj 
short seq_access_num2 
) 


seq access numl SEQ access number 

seq_access_num2 SEQ access number 


SsSeqSetNext specifies the access numberseqaccess _num2of the SEQ data next to be 
performed from SEQ data holdingseqaccessnuml 


None 




SsSeqSetRitardando 


Slows tempo 


Format 

void SsSeqSetRitardando! 
short seq_access_num 
long tempo, 
long v_time 
) 


Arguments 

seq_access_num 
tempo 
v time 


SEQ access number 
Tune tempo 
Time (tick unit) 


Comments 

SsSeqSetRitardando slows the data holdingseqaccess numuntil resolution of tempo in 
v_time 

However, if the specified resolution is greater (faster) than the current resolution, the 
same operation as SsSeqSetAccelerando is carried out. 


Return Value 

None 


See Also 


SsSeqSetAccelerandoO 




SsSeqSetAccelerando 


Accelerates tempo 


Format 

void SsSeqSetAccelerando! 
short seq_access_num 
long tempo, 
long v_time 
) 


Arguments 

seq_access_num 
tempo 
v time 


SEQ access number 
Tune tempo 
Time (tick unit) 


Comments 

SsSeqSetAccelerando accelerates the data holdingseq_access_jiumuntil resolution of 
tempo in v_time 

However, if the specified resolution is smaller (slower) than the current resolution, the 
same operation as SsSeqSetRitardando is carried out. 


Return Value 

None 


See Also 


SsSeqSetRitardando() 




SsSetMVol 


Main volume value setting 


Format 

void SsSetMVol( 
short voll, 
short voir 
) 


L channel volume value 
R channel volume value 


Arguments 


voll 

voir 


Comments 

SsSetMVol sets the main volume value involl and voir respectively. Each can be set from 
0 to 127. 

It is essential to set it before SEQ data is played. 


Return Value 

None 


See Also 


SsGetMVolQ 




SsGetMVol 


Format 


Arguments 


Comments 


Return Value 


See Also 


void SsGetMVol ( 
SndVolume *m_vol 
) 


m vol 


Main volume value 


SsGetMVol assigns the main volume value tom voL 


None 


Gets main volume value 


SsSetMVolQ 




SsSetMute 


Format 


Arguments 


Comments 


Return Value 


See Also 


void SsSetMute ( 
char mode 
) 


mode 


Setting mode 

SS_MUTE ON Mute on 
SS MUTE OFF Mute off 


SsSetMute carries out mute setting. 


None 


Mute setting 


SsGetMute() 




SsGetMute 


Gets mute attributes 


Format 


char SsGetMute ( void ) 


Comments 

SsGetMute gets mute attributes. 


Return Value 


SSMUTEON 
SS MUTE OFF 


Mute attributes. 
Mute on 
Mute off 


See Also 


SsSetMuteQ 




SsPlayBack 


SEQ data reading 


Format 

void SsPlayBack ( 
short access_num 
short seqnurq 
short l_count 
) 


Arguments 

access_num SEQ access number 

seq num Fixed at 0 

l_count Number of tune repetitions 


Comments 

SsPlayBack stops the tune during the current performance, and starts performance by 
returning to the top of that tune. 

It specifies the number of tune repetitions inl_count SSPLAY_INFINITY is specified in 
the case of an infinite number of performances. 


Return Value 

None 


See Also 


SsSeqPlay() 




SsSetTempo 


Format 


Arguments 


Comments 


Return Value 


Sets tempo 


void SsSetTempo( 
short access_num 
short seqnurq 
short tempo 
) 


access_num SEQ access number 

seq num Fixed at 0 

tempo Tune tempo 


SsSetTempo sets the tempo. 

This is valid if the tempo set by SsSeqPlay() is to be changed. After this function has been 
called, the performance is changed to the newly set tempo and played. 


None 




SsIsEos 


Format 


Arguments 


Comments 


Return Value 


Judges whether or not in mid-performance 


short SsIsEos ( 
short access_num 
short seq num 
) 


access_num SEQ access number 

seq num Fixed at 0 


SsIsEos judges whether or not the specified tune is in mid-performance. 


1 is returned if in mid-performance, 0 if not. 




SsSetSerialAttr 


Format 


Arguments 


Comments 


Return Value 


CD audio attribute setting 


void SsSetSerialAttr ( 
char s _num 
char attr, 
char mode 
) 


s num 

Fixed as SS CD 

attr 

Attribute value 

mode 

Setting mode 


SsSetSerialAttr carries out attribute setting relating to CD audio. 


attr = SSMIX 
attr = SS REV 


Mixing 

Reverberation 


mode= SS_SON attr on 

mode=SS SOFF attr off 


None 




See Also 


SsGetSerialAttr() 



SsGetSerialAttr 


Format 


Arguments 


Comments 


Return Value 


See Also 


Gets CD audio attribute value 


char SsGetSerialAttr ( 
char s num 
char attr 
) 


snum Fixed at SS CD 

attr Attribute 


SsGetSerialAttr returns the CD audio attribute value. 


attr = SSMIX 
attr = SS REV 


Mixing 

Reverberation 


Attribute value: 1 is returned if on and 0 if off. 


SsSetSerialAttr() 




SsSetSerialVol 


CD audio volume value setting 


Format 


Arguments 


void SsSetSerialVol( 
short snum, 
short voll, 
short voir 
) 


s num 

Fixed as SS CD 

voll 

L channel volume value 

voir 

R channel volume value 


Comments 

SsSetSerialVol sets the CD volume value involl and voir. 
The volume value can be set from 0 to 127. 


Return Value 

None 


See Also 


SsGetSerialVol() 




SsGetSerialVol 




Gets CD audio volume value 

Format 

void SsGetSerialVol ( 



char s jrnm 



SndVolume *s_vol 



) 


Arguments 

snum 

Fixed at SS CD 


s_vol 

CD audio volume value 

Comments 

SsGetSerialVol returns the CD audio volume value tos_vol. 

Return Value 

None 


See Also 

SsSetSerialVolQ 





SsUtKeyOn 


Keys on voice 


Format 

short SsUtKeyOn ( 
short vabld, 
short prog, 
short tone, 
short note, 
short fine, 
short voll, 
short voir 
) 

Arguments 


vabld 

VAB number 

prog 

Program number 

tone 

Tone number 

note 

Half tone unit pitch specification (note number) 

fine 

Detailed pitch specification (100/127 cent specification) 

voll 

Volume (left) 

voir 

Volume (right) 




Comments 


Return Value 


See Also 


SsUtKeyOn specifies and keys on the volume number (0 to 127), tone number (0 to 15) 
and VAB number for SE, and returns the allocated voice number. 


The voice number (0 to 23) used by key-on is returned. 
-1 is returned in the event of failure. 


SsUtKeyOff(),SsUtAllKeyOff() 



SsUtKeyOff 


Keys off voice 


Format 

short SsUtKeyOff( 
short voice, 
short vabld, 
short prog, 
short tone, 
short note 
) 

Arguments 


voice 

Voice number 

vabld 

VAB number 

prog 

Program number 

tone 

Tone number 

note 

Half tone unit pitch specification (note number) 


Comments 

SsUtKeyOff keys off the voice that was keyed on bjSsUtKeyOn. 


Return Value 

0 is returned if successful, -1 if it fails. 


See Also 


SsUtKeyOnQ, SsUtAllKeyOffQ 




SsUtPitchBend 


Bends pitch 


Format 

short SsUtPitchBend( 

short voice, 

short vabld, 

short prog, 

short note, 

short pbend 

) 


Arguments 


voice 

Voice number 

vabld 

VAB number 

prog 

Program number 

note 

Half tone unit pitch specification (note number) 

pbend 

Pitch bend value 


Comments 

SsUtPitchBend bends pitch of voice keyed on bySsUtKeyOn(). 


Return Value 

0 is returned if successful, -1 if it fails. 


See Also 


SsUtChangePitch() 




SsUtChangePitch 


Changes pitch 


Format 

short SsUtChangePitch( 

short voice, 

short vabld, 

short prog, 

short old_notg 

short old_fine, 

short new not? 

short new_fine 

) 

Arguments 


voice 

Voice number 

vabld 

VAB number 

prog 

Program number 

old_note 

Note number at the time ofSsUtKeyOn 

olde_fine 

Detailed pitch at the time ofSsUtKeyOn (note number) 

new_note 

Note number to be changed 

newftne 

Detailed pitch to be changed (note number) 


Comments 


SsUtChangePitch changes the pitch of the voice keyed on b>SsUtKeyOn(). 




Return Value 

0 is returned if successful, -1 if it fails. 

See Also 

SsUtPitchBendQ 



SsUtSetVVol 


Sets voice volume 


Format 

short SsUtSetVVol( 
short vc, 
short voll, 
short voir 
) 

Arguments 


VC 

Voice number 

voll 

Volume (left) 

voir 

Volume (right) 


Comments 

SsUtSetVVol sets in detail the voice volume keyed on b)8sUtKeyOn(). 


Return Value 

0 is returned if successful, -1 if it fails. 


See Also 


SsUtGetVVol() 




SsUtGetVVol 


Format 


Arguments 


Comments 


Return Value 


See Also 


Gets voice volume 


short SsUtGetVVol( 
short vc, 
short *voll, 
short *volr 
) 


VC 

Voice number 

voll 

Volume (left) 

voir 

Volume (right) 


SsUtGetVVol returns the detailed value of the voice volume keyed on b}SsUtKeyOn(). 


0 is returned if successful, -1 if it fails. 


SsUtSetVVolQ 




SsUtReverbOn 


Format 


Arguments 


Comments 


Return Value 


See Also 


Reverberation on 


void SsUtReverbOn ( void ) 


None 


SsUtReverbOn turns on the reverberation with the set type and depth. 


None 


SsUtReverbOffQ 




SsUtReverbOff 


Format 


Arguments 


Comments 


Return Value 


See Also 


Reverberation off 


void SsUtReverbOff( void ) 


None 


SsUtReverbOff turns the reverberation off. 


None 


SsUtReverbOnQ 




SsUtSetReverbType 


Sets reverberation type 


Format 

short SsUtSetReverbType! 
short type 
) 


Arguments 

type 


Reverberation type 


Type 

Mode 

Delay time * 

Feedback* 

SS_REV_TYPE_OFF 

Off 

X 

X 

SS REV TYPE ROOM 

Room 

X 

X 

S S_RE V_T YPE_S TUDIO A 

Studio (small) 

X 

X 

SS_REV_TYPE_STUDIO_B 

Studio (medium) 

X 

X 

SS_REV_TYPE_STUDIO_C 

Studio (large) 

X 

X 

SS_REV_TYPE_HALL 

Hall 

X 

X 

S S_RE V_T YPES PACE 

Space echo 

X 

X 

SS REV TYPE_ECHO 

Echo 

O 

O 

SSREVTYPEDELAY 

Delay 

O 

O 

SSREVTYPEPIPE 

Pipe echo 

X 

X 


* Delay time and Feedback specification by reverberation type is possible 


Comments 

SsUtSetReverbType sets the reverberation type. 

The reverberation depth is automatically set to 0 when the reverberation type is set. 

When data is left in the reverberation work area, noise appears as soon as the depth is set, 
so the following procedure should be used. 





SsUtSetReverbType(SS_REV...); 

SsUtReverbOnQ; 


Takes several seconds 
SsUtSetReverbDepth(64,64); 
Number and type response as above 


Return Value 

If setting is carried out correctly, the set type number is returned. 
If setting is carried out incorrectly, -1 is returned. 


See Also 

SsUtGetReverbType( ), SsUtSetReverbDepthQ, SsUtSetReverbFeedback( ), 
SsUtSetReverbDelayQ 



SsUtGetReverbType 


Gets reverberation type 


Format 


short SsUtGetReverbType! void ) 


Arguments 

None 


Comments 

SsUtGetReverbType gets the current reverberation type value. 


Return Value 

Current reverberation type value 


See Also 


SsUtSetReverbType() 




SsUtSetReverbDepth 


Format 


Arguments 


Comments 


Return Value 


See Also 


void SsUtSetReverbDepth! 
short ldepth, 
short rdepth 
) 


ldepth 0-127 

rdepth 0-127 


SsUtSetReverbDepth sets the reverberation depth. 


None 


Sets reverberation depth 


SsUtSetReverbType() 




SsUtSetReverbFeedback 


Format 


Arguments 


Comments 


Return Value 


See Also 


Sets feedback amount 


void SsUtSetReverbFeedback! 
short feedback 
) 


feedback 0-127 


SsUtSetReverbFeedback sets the feedback amount if the echo type reverberation is used. 


None 


SsUtSetReverbTypeQ 




SsUtSetReverbDelay 


Format 


Arguments 


Comments 


Return Value 


See Also 


Sets delay amount 


void SsUtSetReverbDelay! 
short delay 
) 


delay 0-127 


SsUtSetReverbDelay sets thedelayamount if the echo and delay type reverberation is 
used. 


None 


SsUtSetReverbTypeQ 




SsUtAllKeyOff 


Format 


Arguments 


Comments 


Return Value 


See Also 


Keys off all voices 


void SsUtAllKeyOff( 
short mode 
) 


mode Always 0 


SsUtAllKeyOff compulsorily keys off all voices used by the sound service. 


None 


SsUtKeyOnQ, SsUtKeyOffQ, SsSeqPlayQ 





Standard C Functions 




abs 


Format 


Arguments 


Comments 


Return Value 


See Also 


Calculates absolute value 


#include <stdlib.h> 
long abs ( 
long i 
) 


Integer value 


abs calculates the absolute value of the integeri. This function is primarily for searching 
the absolute value ofint type integers. However, asint type and long type have the same 
meaning in R3000, on this system it is a function equivalent to labs described next. 


The absolute value of the argument is returned. 


labsQ 




labs 


Format 


Arguments 


Comments 


Return Value 


See Also 


Calculates absolute value 


#include <stdlib.h> 
long labs ( 
long i 
) 


Integer value 


labs calculates the absolute value of the integeri. On this system, it is a function 
equivalent to abs described previously. 


The absolute value of the argument is returned. 


abs() 




atoi 


Converts character strings to integers 


Format 

#include <stdlib.h> 
long atoi ( 
const char *s 
) 


Arguments 


Character string 


Comments 

atoi is the same as (long)strtol(s,(char**)NULL). On this system it is a function 
equivalent to atoi, which follows on next page. 


Return Value 

The result of converting the input values to an integer is returned. 


See Also 


atolQ, strtolQ 




atol 


Format 


Arguments 


Comments 


Return Value 


See Also 


Converts character strings to integers 


#include <stdlib.h> 
long atol( 
const char *s 
) 


s 


Character string 


atol is the same as (long)strtol(s,(char**)NULL). 


The result of converting the input values to an integer is returned. 


atoi(),strtol() 




bzero 


Format 


Arguments 


Comments 


Return Value 


See Also 


Pads memory blocks with zeros 


#include <memory.h> 
void *bzero( 
unsigned char *p, 
int n 
} 


p Pointer to write start position 

n Write byte number 


Writes n byte zeros from the address specified byp. 


Returns the pointer to the address where write starts. 


bcopy(), bcmpQ 




bcopy 


Format 


Arguments 


Comments 


Return Value 


See Also 


#include <memory.h> 

voidbcopy( 

char *src, 

char *dest, 

long n 

) 


src 

Copy source 

dest 

Copy destination 

n 

Copy byte number 


bcopy copies the firstn byte of src to dest. 


None 


Copies memory blocks 


memcpyO 




bcmp 


Compares memory blocks 


Format 

#include <memory.h> 

longbcmp( 

char *bl, 

char *b2, 

long n 

) 

Arguments 


bl 

Comparison source 1 

b2 

Comparison source 2 

n 

Comparison byte number 


Comments 

bcmp compares the firstn bytes ofbl and b2. 


Return Value 

The next value depending on the comparison result ofb 1 and b2 is returned. 


Result 

Return Value 

bl<b2 

<0 

bl=b2 

=0 

bl>b2 

>0 





See Also 


memcmpQ 



bsearch 


Carries out binary searches 


Format 


Arguments 


#include <stdlib.h> 
void *bsearch ( 
const void *key, 
const void *base, 
size_t n, 
size_t w, 


long(*fcmp)(const void 
) 

*, const void *) 

key 

Storage destination of retrieved value 

base 

Storage destination of retrieved array 

n 

Number of elements 

w 

Size of 1 element 

fcmp 

Comparison function 


Comments 

With fcmp as a comparison function, bsearch carries out a binary search of tables ofn 
items (size of item =w) starting from base, looking for items matchingkey. 


Return Value 


The address of the first item matching the retrieval key is returned. 0 is returned if there is 
no matching item. 




calloc 


Allocates main memory 


Format 

#include <stdlib.h> 
void *calloc ( 
size_t n, 
size_t s 
) 


Number of articles 
Block size 


Arguments 

n 

s 


Comments 

calloc secures the n x s byte block from the heap memory. 


Return Value 

The pointer to the secured memory block is returned. 
NULL is returned in the event of failure. 


See Also 


malloc(), reallocQ, freeQ 




malloc 


Format 


Arguments 


Comments 


Return Value 


See Also 


Allocates main memory 


#include <stdlib.h> 
void *malloc ( 
size_t s 
) 


s 


Characters to be tested 


malloc secures the s byte block from the heap memory. 


The pointer to the secured memory block is returned. 

NULL is returned in the event of failure to secure. 

* At the time of user program activation the heap memory is defined as follows. 
Lowest address Module’s highest address + 4 

Highest address Package memory* 64KB 


callocQ, reallocQ, freeQ 




realloc 


Format 


Arguments 


Comments 


Return Value 


See Also 


Reallocates heap memory 


#include <stdlib.h> 
void *realloc ( 
void *block, 
size_t s 
) 


block Area to be reallocated 

s Area size 


realloc reduces or enlarges the blockblockthat was previously secured tos byte. Ifblock 
is NULL, it has the same operation asmallocQ. 


The reallocated block address is returned. This address may be different from the original 
address. NULL is returned in the event of failure to allocate. At this time the original 
block cannot be opened. 


callocQ, mallocQ, free() 




free 


Format 


Arguments 


Comments 


Return Value 


See Also 


Opens allocated memory blocks 


#include <stdlib.h> 
void free ( 
void*block 
) 


block 


Area to be opened 


free opens the memory block secured bycalloc(), mallocQ andrealloc(). 


None 


calloc(), malloc(), realloc() 




memchr 


Searches for characters in memory blocks 


Format 

#include <memory.h> 
void *memchr ( 
const void *s, 
long c, 
sizet n 
) 


Retrieved characters storage destination 
Retrieved characters 
Number of retrieved bytes 


Arguments 

s 

c 

n 


Comments 

memchr locates the first appearance of the characterc in the memory block of then byte 
starting from s. 


Return Value 

The pointer to the located character is returned. NULL is returned whenc cannot be 
discovered. 




memcmp 

Carries out memory block comparison 


Format 

#include <memory.h> 
long memcmp ( 
const void *sl, 
const void *s2, 
size_t n 
) 


Arguments 

sl 

Comparison source 1 


s2 

Comparison source 2 


n 

Comparison byte number 

Comments 




memcmp compares the firstn bytes ofsl and s2. 


Return Value 

The following values are returned depending on the comparison result ofil and s2. 


Result 

Return Value 

sl<s2 

<0 

sl=s2 

=0 

sl>s2 

>0 


See Also 


bcmp() 





memcpy 


Format 


Arguments 


Comments 


Return Value 


See Also 


#include <memory.h> 
void *memcpy( 
void *dest, 
const void *src, 
size_t n 
) 


dest 

Copy destination 

src 

Copy source 

n 

Copy byte number 


memcpy copies the firstn byte of src to dest 


dest is returned. 


Copies memory blocks 


bcopy() 




mem move 


Copies memory blocks 


Format 

#include <memory.h> 
void *memmove( 
void *dest, 
const void *src, 
size_t n 
) 

Arguments 


dest 

Copy destination 

src 

Copy source 

n 

Copy byte number 


Comments 

memmove copies the firstn byte of src to dest 

Accurate copying is performed even among duplicated objects. 


Return Value 


dest is returned. 




mem set 


Writes specified characters to memory blocks 


Format 

#include <memory.h> 
void *memset ( 
const void *s, 
long c, 
size_t n 
) 


Memory block 
Character 
Character number 


Arguments 

s 

c 

n 


Comments 

memset writes c to the n byte memory block starting froms. 


Return Value 


s is returned. 




qsort 


Carries out quick sort 


Format 

#include <stdlib.h> 
void qsort ( 
void *base, 
size_t n, 
size_t w, 

long (*fcmp)(const void *, const void *) 

) 


Arguments 


base 

Storage destination of array to be sorted 

n 

Number of elements 

w 

Size of 1 element 

fcmp 

Comparison function 


Comments 

With fcmp as a comparison function, qsort sorts a table ofn number of items (size of item 
= w) starting from base. 

Take care with the empty heap area becausemallocQ is called internally. 


Return Value 


None 




srand 


Format 


Arguments 


Comments 


Return Value 


See Also 


Initialises random number generator 


#include <stdlib.h> 
void srand ( 
unsigned int seed 
) 


seed 


Random number 


srand sets the new starting point of the random number generation. Default is 1 . 


None 


randQ 




rand 


Format 


Arguments 


Comments 


Return Value 


See Also 


Generates random numbers 


#include <stdlib.h> 
long rand ( void ) 


None 


rand generates pseudo random numbers between RAND_MAX(0x7FFF=32767) from 0. 


A generated pseudo random number is returned. 


srandQ 




strcat 


Format 


Arguments 


Comments 


Return Value 


See Also 


Adds one character string to another 


#include <strings.h> 
char *strcat ( 
char *dest, 
const char *src 
) 


dest Link destination character string 

src Link source character string 


strcat adds src to the end of the character string dest. 


dest is returned. 


stmcatQ 




strchr 


Searches for position of first appearance of a specified 

character in a character string 


Format 

#include <strings.h> 
char *strchr ( 
const char *s, 
long c 
) 


Retrieved character string 
Retrieved character 


Arguments 

s 

c 


Comments 

strchr searches for the position where the characterc first appears in the character string s. 


Return Value 

The address of the appearance position ofc is returned. NULL is returned ifc does not 


appear. 




strcmp 


Compares character strings 


Format 

#include <strings.h> 
long strcmp ( 
const char *s 1 , 
const char *s2 
) 

Arguments 

si Comparison source 1 

s2 Comparison source 2 

Comments 

strcmp compares each character ofs 1 and s2 as unsigned char. 


Return Value 

The following values are returned depending on the comparison result ofil and s2. 


Result 

Return Value 

sl<s2 

<0 

sl=s2 

=0 

sl>s2 

>0 













strep y 


Copies one character string to another 


Format 

#include <strings.h> 
char *strcpy ( 
char *dest, 
const char *src 
) 


Copy destination character string 
Copy source character string 


Arguments 


dest 

sre 


Comments 

strepy copies sre to the character string dest. 


Return Value 

dest is returned. 


See Also 


stmcpyO 




strcspn 


Format 


Arguments 


Comments 


Return Value 


Searches for first part of a character string comprising only 
characters not included in specified character set 


#include <strings.h> 
size_t strcspn ( 
const char *s 1 , 
const char *s2 
) 


sl 

Character string 

s2 

Character group 


strcspn returns the length of the first part of a character string comprising only characters 
not included in the character string s2 within the character string si. 


The length of the found section of the character string is returned. 




strlen 


Format 


Arguments 


Comments 


Return Value 


Finds the number of characters in character string 


#include <strings.h> 
long strlen ( 
const char *s 
) 


s 


Character string 


strlen counts number of characters in the character strings. 


The character number is returned. 




strncat 


Format 


Arguments 


Comments 


Return Value 


Adds one character string to another 


#include <strings.h> 
char *strncat ( 
char *dest, 
const char *src, 
size_t n 
) 


dest 

Link destination array 

src 

Link source character string 

n 

Link character number 


strncat adds the largest n character fromsrc to end of character string dest 


dest is returned. 




strncmp 


Compares character strings 


Format 

#include <strings.h> 
long stncmp ( 
const char *s 1 , 
const char *s2, 
size_t n 
) 

Arguments 


si 

Comparison source 1 

s2 

Comparison source 2 

n 

Comparison character number 


Comments 

strncmp compares as unsigned char all characters as far assl and s2 top n characters. 


Return Value 

The following values are returned depending on the result of the comparison. 


Result 

Return 

sl<s2 

<0 

sl=s2 

=0 

sl>s2 

>0 




strncpy 


Copies one character to another 


Format 

#include <strings.h> 
char *strncpy( 
char *dest, 
const char *src, 
size_t n 
) 


Copy destination character string 
Copy source character string 
Copy byte number 


Arguments 

dest 

src 

n 


Comments 

stmcpy copies n bytes of src to the character string dest. It stops copying when the number 
of characters added reaches n. 


Return Value 


dest is returned. 




strpbrk 


Searches for position of first appearance of a specified 

character in a character set 


Format 

#include <strings.h> 
char *strpbrk ( 
const char *s 1 , 
const char *s2 
) 

Arguments 


sl 

Retrieved character string 

s2 

Character group 


Comments 

strpbrk checks the character string si and searches the position where any one character 
included in the character group s2 first appears. 


Return Value 


The address of the found character is returned. NULL is returned if it is not found. 




strrchr 


Searches for position of last appearance of a specified 

character in a character string 


Format 

#include <strings.h> 
char *strrchr ( 
const char *s, 
long c 
) 

Arguments 

s Retrieved character string 

c Retrieved character 

Comments 

strrchr searches the position where the characterc last appears in the character string s. 


Return Value 

The address of the appearance position ofc is returned. NULL is returned ifc does not 


appear. 




strspn 


Searches for first part of a character string comprising only 

characters in a specified character set 


Format 

#include <strings.h> 
size_t strspn ( 
const char *sl, 
const char *s2 
) 

Arguments 


sl 

Retrieved character string 

s2 

Character group 


Comments 

strspn returns the length of the first section that comprises only characters that are 
included in the character group s2 within the character string s 1 . 


Return Value 


The length of the found section of the character string is returned. 




strstr 


Searches for position of appearance of specified partial 

character string 


Format 

#include <strings.h> 
char *strstr ( 
const char *s 1 , 
const char *s2 
) 

Arguments 


sl 

Retrieved character string 

s2 

Retrieved character string 


Comments 

strstr checks the character string si and searches the position where the character string s2 
first appears. 


Return Value 


The address of the position found is returned. NULL is returned if it is not found. 




strtok 


Searches for a character string bounded by characters in a 

specified character set 


Format 

#include <strings.h> 
char *strtok ( 
char *sl, 
const char *s2 
) 


Retrieved character string 
Bounded character group 


Arguments 


si 

s2 


Comments 

strtok takes the character string s 1 as a set of tokens bounded by one or more characters 
within the separate character string s2. 

The first token top address of si is returned when strtok is first called, and directly after 
the token, the character NULL is written. After thes 1 address is stored in the function, 
when NULL is entered in the first argument andstrtok is called, a search is carried out 
until the token in the character string si disappears. 


Return Value 

The top address of the tokens found in si is returned. NULL is returned if nothing is 
found. 




strtol 


Converts character strings to integers 


Format 

#include <stdlib.h> 
long strtol ( 
const char *s, 
char **endp 
) 


Arguments 

s Character string 

endp Storage destination of pointer to non-convertible character 

string 


Comments 

strtol converts the character strings to long type (same asint type in R3000). 
s must be in the following format. 


[ws][sn][ddd] 

[ws] 

[sn] 

[ddd] 


White space (can be omitted) 
Sign (can be omitted) 

Number string (can be omitted) 


strtol stops conversion when a character is encountered that cannot be converted and, 
unless endp is NULL, it sets the pointer to the character that stopped conversion toendp. 




Return Value 

The result of converting the input values to an integer is returned. 0 is returned when an 
error occurs. 

See Also 

strtoulQ 



strtoul 


Converts character string into unsigned integer 


Format 

#include <stdlib.h> 
unsigned long strtoul ( 
const char *s, 
char **endp 
) 


Arguments 

s Character string 

endp Storage destination of pointer to non-convertible character 

string 


Comments 

strtoul converts the character strings to unsigned long type (same as unsignedint type in 
R3000). 

s must be in the following format. 

[ws][sn][ddd] 

[ws] White space (can be omitted) 

[sn] Sign (can be omitted) 

[ddd] Number string (can be omitted) 

strtoul stops conversion when a character is encountered that cannot be converted and, 
unless endp is NULL, it sets the pointer to the character that stopped conversion tcendp. 




Return Value 


The result of converting the input values to an integer is returned. 


See Also 


strtol() 



isXXX 


Carries out character testing 


Format 

#include <ctype.h> 
long isXXX ( 
long c 
) 


Arguments 

c Character 

Comments 

isXXX carries out testing of characterc. They are all macros. The test conditions are as 
follows. 


Function Name 

Condition 

isalnum 

isalpha(c) ||isdigit(c) 

isalpha 

isupper(c) ||islower(c) 

isascii 

ASCII characters 

iscntrl 

Control characters 

isdigit 

10 base 

isgraph 

Printable characters except spaces 

islower 

Lower case characters 

isprint 

Printable characters including spaces 

ispunct 

Printable characters except spaces, English letters and numbers 

isspace 

Spaces, page breaks, line feeds, character returns, tabs 

isupper 

Upper case letters 

isxdigit 

Hexadecimal 































Return Value 


A value other than 0 is returned if the input value c satisfies the conditions, and 0 
returned if the conditions are not satisfied. 



toascii 


Format 


Arguments 


Comments 


Return Value 


Masks 7th bit of an input value 


#include <ctype.h> 
long toascii ( 
long c 
) 


c 


Input value 


toascii is a macro for masking the 7th bit. 


The value masking the 7th bit of the input valuec is returned. 




tolower 


Format 


Arguments 


Comments 


Return Value 


Converts characters to lower case characters 


#include <ctype.h> 
long tolower ( 
long c 
) 


c 


Input value 


tolower is a macro for converting the input valuec to a lower case character. 


The lower case character corresponding to the input valuec. 




toupper 


Format 


Arguments 


Comments 


Return Value 


Converts characters to upper case characters 


#include <ctype.h> 
long toupper ( 
long c 
) 


c 


Input value 1 


toupper is a macro for converting the input valuec to an upper case character. 


The upper case character corresponding to the input valuec. 




getc 


Format 


Arguments 


Comments 


Return Value 


See Also 


Gets a single character from the stream 


#include <stdio.h> 
char getc ( 

FILE *stream 

) 


stream 


Input stream 


Gets a single character from input streamstream. 


NULL is returned in the case of file end or error. 


getchar(), getsQ 




getchar 


Format 


Arguments 


Comments 


Return Value 


See Also 


Gets a single character from the standard input stream 


#include <stdio.h> 
char getchar( void ) 


None 


getchar gets a single character from the standard input stream. It is the same asgetc 
(stdin). 


Same as getc. 


getc(), gets() 




gets 


Reads in a character string from the standard input stream 


Format 

#include <stdio.h> 
char *gets ( 
char *s 
) 


Arguments 

s 


Input array storage destination 


Comments 

gets reads in the array that ends with a line feed character from the standard input stream 
(stdin) and stores it in s. 


Return Value 

The character string arguments is returned when successful. NULL is returned in the case 
of file end or error. 


See Also 


getc(), getchar() 




putc 


Format 


Arguments 


Comments 


Return Value 


See Also 


Outputs a single character to the stream 


#include <stdio.h> 
void putc ( 
long c, 

FILE Stream 

) 


c Output character 

stream Output stream 


putc outputs the character c to the output stream stream 


None 


putchar(), puts() 




putchar 


Format 


Arguments 


Comments 


Return Value 


See Also 


Outputs a single character to standard output stream 


#include <stdio.h> 
long putchar( 
char c, 

) 


c 


Output character 


putchar outputs a single character to the standard output stream. It is the same as putc 
(stdout). 


None 


putc(), puts() 




puts 


Format 


Arguments 


Comments 


Return Value 


See Also 


Outputs a character string to the standard output stream 


#include <stdio.h> 
void puts ( 
const char *s 
) 


s Output character string 

puts outputs the character string closed by NULL to the standard output stream (stdout), 
and finally outputs the line feed character. 


None 


putc(), putcharQ 




printf 


Carries out formatted output to standard output stdout 


Format 

#include <stdio.h> 
long printf ( 

const char *fint[, argument ...] 

) 


Arguments 

fint 


Input format character string 


Comments 

Please refer to C language reference books for a detailed explanation of input format. 
Not compatible with conversion specifiers “f “e”, “E”, “g” and “G”. 
printf2() of the mathematical function service is used in floating-point display. 


Return Value 

The length of the output character string is returned. NULL is returned when an error 
occurs. 


See Also 


sprintf(), printf2() 




sprintf 


Format 


Arguments 


Comments 


Return Value 


See Also 


Format output to array 


#include <stdio.h> 
long sprintf( 
char *s, 

const char *fint[, argument...] 

) 

s Storage destination of conversion character string 

fint Input format character string 


Please refer to C language reference books for a detailed explanation of input format. 
Not compatible with conversion specifiers “f “e”, “E”, “g” and “G”. 
sprintf2() of the mathematical function service is used in floating-point display. 


The length of the output character string is returned. NULL is returned when an error 
occurs. 


printf(), sprintfTQ 




setjmp 


Format 


Arguments 


Comments 


Return Value 


See Also 


Defines arrival point of non-local jump 


#include <setjmp.h> 
int setjmp ( 
jmpbuf p 
) 


P 


Environment evacuation variable 


Stores non-local jump arrival point information inp. When longjmp(p,val) is executed, it 
returns from setjmpQ. 


With direct calling 0 is returned. 

When jump is carried out the value supplied to the second argument of longjmp() is 
returned. 


longjmpO 




longjmp 


Format 


Arguments 


Comments 


Return Value 


See Also 


Non-local jump 


#include <setjmp.h> 
void longjmp ( 
jmp buf p, 
int val 
) 


p Environment evacuation variable 

val Return value of setjmpQ 


Jumps non-locally to arrival point specified byp. 


None. Not returned when executed normally. 


setjmp() 





Mathematical Functions 




fabs 


Format 


Arguments 


Comments 


Return Value 


Notes 


Absolute value (macro) 


fabs ( 
double x 
) 


x 


Floating-point value 


fabs looks for the absolute value. 


The absolute value ofx 


This is a macro 




atof 


Converts character strings to floating-point numbers 


Format 

double atof( 
const char *s 
) 


Arguments 

s 


Character string 


Comments 

atof converts character string to floating-point numbers (double type). 


Return Value 

The result of converting the input values to double type is returned. If the correct value 
exceeds the range that can be expressed, either +HUGE_VAL( 1.7976931 348623 16e+308) 
or -HUGE_VAL is returned according to the sign. 0 is returned if an underflow occurs. 


Notes 

Error processing is as follows. 


Condition 

Return Value 

Error 

Outside the range that can 
be expressed 

+/- HUGEVAL 

Domain error 

Underflow occurrence 

0 

Domain error 


See Also 


strtod() 





strtod 


Converts character strings to floating-point numbers 


Format 

double strtod) 
const char *s, 
char **endp 
) 


Arguments 

s Character string 

endp Storage destination of pointer to non-convertible character 

string 


Comments 

strtod converts the character strings to double type, 
s must be in the following format. 


[ws][sn][ddd] 

[ws] 

[sn] 

[ddd] 


White space (can be omitted) 
Sign (can be omitted) 

Number string (can be omitted) 


strtod stops conversion when a character is encountered that cannot be converted and, 
unless endp is NULL, it sets the pointer to the character that stopped conversion toendp. 




Return Value 


The result of converting the input values to double type is returned. If the correct value 
exceeds the range that can be expressed, either +HUGE_VAL( 1.7976931 348623 16e+308) 
or -HUGEVAL is returned, according to the sign. 0 is returned if an underflow occurs. 


Notes 

Error processing is as follows. 


Condition 

Return Value 

Error 

Outside the range that can 
be expressed 

+/- HUGEJVAL 

Domain error 

Underflow occurrence 

0 

Domain error 




pow 


x to the power of y 


Format 

double pow ( 
double x, 
double y 
) 

Arguments 

x Number value 

y Power 


Comments 

pow calculates x to the power ofy. 


Return Value 

x to the power ofy (x y ) 


Notes 

Error processing is as follows. 


Condition 

Return Value 

Error 

x==0 && y>0 

0 


x==0 && y<=0 

1 

Domain error 

x<0 && “y is not Integer value” 

0 

Domain error 















See Also 


exp() 



exp 


Format 


Arguments 


Comments 


Return Value 


See Also 


Exponent 


double exp ( 
double x 
) 


x 


Floating-point value 


exp looks for the exponent function ofx. 


e to the power ofx (e x ) 


P°w(), log() 




log 


Format 


Arguments 


Comments 


Return Value 


Notes 


See Also 


Natural logarithm 


double log ( 
double x 
) 


x 


Logarithm calculated value 


log looks for the logarithm function oix. 


x logarithm ( ln(x) ) 


x is greater than 0. Range error in the case of others. 


Condition 

Return Value 

Error 

x<0 

0 

Domain error 

x==0 

1 

Range error 


exp(), logl0() 












Base 10 logarithm 


log 10 


Format 


Arguments 


Comments 


Return Value 


Notes 


See Also 


double log 10 ( 
double x 
) 


x 


Logarithm calculated value 


log looks for the base 1 0 logarithm function oft. 


xbase 10 logarithm ( logl0(x) ) 


x is greater than 0. Range error in the case of others. 


Condition 

Return Value 

Error 

x<0 

0 

Domain error 

x==0 

1 

Range error 


log() 












floor 


Largest integer not greater than x (base function) 


Structure 

double floor ( 
double x 
) 

Arguments 

x Floating-point value 

Comments 

floor looks for the largest integer (double type) that is not greater thanx. 

Return value 

Largest integer (double type) that is not greater thanx 

See Also 

ceil() 




ceil 


Structure 


Arguments 


Comments 


Return value 


See Also 


Smallest integer not smaller than x (ceiling function) 


double ceil ( 
double x 
) 


x 


Floating-point value 


ceil looks for the smallest integer (double type) that is not smaller thanx. 


Smallest integer (double type) that is not smaller than x 


floorQ 




fmod 


Structure 


Arguments 


Comments 


Return value 


Notes 


x/y floating-point number remainder 


double fmod ( 
double x, 
double y 
) 


x Floating-point value 

y Floating-point value 


fmod looks for the remainder of the floating-point number resulting fronx/y. 


Floating-point number remainder ofx/y 


Return value sign is the same asx. 0 is returned if y is 0. 




modf 


Structure 


Arguments 


Comments 


Return value 


Notes 


Separation into integer parts and fractional parts 


double modf ( 
double x, 
double *y 
) 


x Floating-point value 

y Pointer to the buffer for storing integer part 


modf separates x into integer parts and fractional parts. 

The integer part is stored in y, and the fractional part becomes the return value. 


Fractional part ofx 


The sign for both integer parts and fractional parts is the same asx. 




sin 


Sine 


Structure 

double sin ( 
double x 
) 

Arguments 

x Angle in radian units 

Comments 

sin looks for the sine function ofx. 

Return value 

sine function ofx(sin(x)) 


See Also 


cos(), tan(), asinQ 




cos 


Structure 


Arguments 


Comments 


Return value 


See Also 


Cosine 


double cos ( 
double x 
) 


x 


Angle in radian units 


cos looks for the cosine function oft. 


cosine function ofx (cos(x) ) 


sin(), tan(), acosQ 




tan 


Structure 


Arguments 


Comments 


Return value 


See Also 


Tangent 


double tan ( 
double x 
) 


x 


Angle in radian units 


tan looks for the tangent function ofx. 


tangent function ofx (tan(x) ) 


sin(), cos(), atanQ 




asin 

Arcsine 

Structure 

double asin ( 
double x 
) 

Arguments 

x Arcsine calculation value. Range is [-1 to 1], 

Comments 

asin looks for the arcsine function ofx. 

Return value 

Arcsine function ofx. The range is [-pi/2, pi/2]. 

Error processing is as follows. 


Condition 

Return value 

Error 

fabs(x)>l 

0 

Domain error 


Notes 

[ ] shows the closed area. 

See Also 

sin(), acosQ, atanQ 





acos 


Arccosine 


Structure 

double acos ( 
double x 
) 


Arguments 

X 


Arccosine calculation value. Range is [-1 to 1], 


Comments 

acos looks for the arccosine function olx 


Return value 

Arccosine function ofx. The range is [0 to pi]. 
Error processing is as follows. 


Condition 

Return value 

Error 

fabs(x)>l 

0 

Domain error 


Notes 

[ ] shows the closed area. 


See Also 


cos(), asin(), atanQ 





atan 


Structure 


Arguments 


Comments 


Return value 


Notes 


See Also 


double atan ( 
double x 
) 


x 


Arctangent calculation value 


atan looks for the arctangent function ofx. 


Arctangent function ofx. The range is [-pi/2 to pi/2] 


[ ] shows the closed area. 


Arctangent 


tan(), asin(), acosQ, atan2() 




atan2 


Arctangent 


Structure 

double atan2 ( 
double x, 
double y 
) 

Arguments 

x Floating-point value 

y Floating-point value 


Comments 

atan2 looks for the arctangent function ofx/y. 


Return value 

Arctangent function ofx/y. The range is [-pi to pi]. 
Error processing is as follows. 


Condition 

Return value 

Error 

x==0 &&y==0 

0 

Domain error 


Notes 

[ ] shows the closed area. 

See Also 


atan() 





sinh 


Structure 


Arguments 


Comments 


Return value 


See Also 


double sinh ( 
double x 
) 


x 


Angle in radian units 


sinh looks for the hyperbolic sine function oft. 


Hyperbolic sine function ofx ( sinh(x) ) 


Hyperbolic sine 


cosh(), tanh() 




cosh 


Structure 


Arguments 


Comments 


Return value 


See Also 


double cosh ( 
double x 
) 


x 


Angle in radian units 


cosh looks for the hyperbolic cosine function oix. 


hyperbolic cosine function ofx ( cosh(x) ) 


Hyperbolic cosine 


sinh(), tanh() 




tanh 


Structure 


Arguments 


Comments 


Return value 


See Also 


double tanh ( 
double x 
) 


x 


Angle in radian units 


tanh looks for the hyperbolic tangent function olx. 


Hyperbolic tangent function oix ( tanh(x) ) 


Hyperbolic tangent 


sinhQ, cosh() 




sqrt 


Square root 


Structure 

double sqrt ( 
double x 
) 


Arguments 

X 


Floating-point value that is not negative 


Comments 

sqrt looks for the square root ofx 


Return value 

Square root ofx 

Error processing is as follows. 


Condition 

Return value 

Error 

x<0 

0 

Domain error 





hypot 


Structure 


Arguments 


Comments 


Return value 


Complex number absolute value 


double hypot ( 
double x, 
double y 
) 


x Floating-point value 

y Floating-point value 


hypot looks for the absolute value of the complex number £+iy). 


2 2 

Square root of the sum of x and y“ 




Calculates real number from mantissa and exponent (xx2 n ) 


Id exp 


Structure 


Arguments 


Comments 


Return value 


double ldexp ( 
double x, 
long n 
) 


x Floating-point value 

n Integer exponent 


ldexp calculates the real number from the mantissa and exponent. 


The value of x x 2 




frexp 


Resolution into normalised fractional part and 2 n part 


Structure 

double frexp ( 
double x, 
int *11 
) 


Floating-point value 

Pointer to the buffer that stores the 2 n part 


Arguments 

X 

n 


Comments 

frexp resolves x into fractional parts normalised to [1/2,1 ) and 2 n parts. The fractional 
part becomes the return value and the 2 n part is stored in n. 


Return value 

Normalised fractional part [1/2, 1) 


Notes 


[ ] shows the closing section and () the opening section. 




printf2 


Formatted output of standard output stdout (supports float and double 

type) 

Structure 

long printf2( 

const char *fint, [argument...] 

) 

Arguments 

lint Output format character string 

Comments 

The conversion specifiers “f “e”, “E”, “g” and “G” can be used. 

The stack consumption amount is greater than printf. 

Return value 

The length of the output character string is returned. 


See Also 


sprintf2() 




sprintf2 


Formatted output to array (supports float and double type) 


Structure 

long sprintf2( 
char *s, 

const char *fint, [argument...] 

) 

Arguments 

s Storage destination of converted character string 

lint Output format character string 

Comments 

The conversion specifiers “f “e”, “E”, “g” and “G” can be used. 

The stack consumption amount is greater than printf. 


Return value 

The length of the output character string is returned. 


See Also 


printf2() 





Other Functions 




EXEC 


Executable file data structure 


Structure 

struct EXEC { 


unsigned long pcO; 
unsigned long gpO; 
unsigned long t_addr; 
unsigned long t_size; 
unsigned long d_addr; 
unsigned long d_size; 
unsigned long s_addr; 
unsigned long s_size; 
unsigned long sp, fp, gp, base; 


Members 

pcO 

gpO 

t_addr 

t_size 

daddr 

d_size 

b_addr 

b_size 

s_addr 

s size 


Execution start address 
gp register initial value 

Data session top address with text session + initial value 

Data session size with text session + initial value 

Reserved for the system 

Reserved for the system 

Data session top address without initial value 

Data session size without initial value 

Stack area top address (for user specification) 

Stack area size (for user specification) 

Register evacuation area 


sp,fp,gp,base 




Comments 


EXEC is arranged in the top 2k bytes of the executable file (PS-X EXE structure). It holds 
information for loading and executing the program that is stored in the file. 

It activates the program by adding stack infonnation and delivering it to the Exec() 
function. 

See Also 

ExecQ 



DIRENTRY 


Directory entry data structure 


Structure 

struct DIRENTRY { 

char name[20]; 
long attr; 
long size; 

struct DIRENTRY Tiext 
long head; 
char system[8]; 

} 

Members 


name 

Filename 

attr 

Attribute (depends on file system) 

size 

File size (byte units) 

next 

Next file entry (for user) 

head 

Head sector 

system 

Reserved for the system 


Comments 

DIRENTRY stores information relating to files that are registered in the file system. 


See Also 


firstfile(), nextfile() 




CdlLOC 


CD-ROM location 


Structure 

typedef struct { 

u_char minute; 
u_char second; 
u_char sector; 
u_char track; 

} CdlLOC; 

Members 


minute 

Minute 

second 

Second 

sector 

Sector 

track 

Track number 


Comments 

CD location specification structure. 


Notes 


track members are not currently used. 




CdlFILE 


ISO-9660 file descriptor 


Structure 

typedef struct { 

CdlLOCpos; 
u_long size; 
char name[16]; 

} CdlFILE; 

Members 


pos 

File position 

size 

File size 

name 

Filename 


Comments 


CdlFILE gets the ISO-9660 CD-ROM file location and size. 




GetRCnt 


Structure 


Arguments 


Comments 


Return value 


See Also 


Getting root counter 


long GetRCnt ( 
unsigned long spec 
) 


spec 


Root counter specification 


GetRCnt returns the current value of the root counterspec. 


The counter value that is expanded without the sign in 32bit is returned when successful, 
and -1 is returned in the event of failure. 


StartRCntQ, ResetRCntQ 




ResetRCnt 


Structure 


Arguments 


Comments 


Return value 


See Also 


Resetting root counter 


long ResetRCnt( 
unsigned long spec 
) 


spec 


Root counter specification 


ResetRCnt resets the root counterspec. 


1 is returned when successful, and 0 in the event of failure. 


GetRCntQ, StartRCnt() 




StartRCnt 


Structure 


Arguments 


Comments 


Return value 


See Also 


Root counter activation 


long StartRCnt ( 
unsigned long spec 
) 


spec 


Root counter specification 


StartRCnt activates the root counterspec. 


1 is returned when successful, and 0 in the event of failure. 


GetRCnt(), ResetRCntQ 




Enter /ExitCriticalSection 


Structure 


Arguments 


Comments 


Return value 


Interruption inhibited/permitted 


void EnterCriticalSection(void) 
void ExitCriticalSection(void) 


None 


EnterCriticalSection() inhibits interruption 
ExitCriticalSection() permits interruption. 


None 




open 


Opening file 


Structure 

int open ( 
char *devname; 
int flag 
) 

Arguments 

devname Filename 

flag Open mode 


Comments 

open opens the file devnameand returns its descriptor. 
Macros that can be specified inflag are as follows. 


Macro 

Open mode 

O RDONLY 

Read only 

O WRONLY 

Write only 

O RDWR 

Read and write 

O CREAT 

Create file 

OJNOBUF 

No buffer mode 

OJNOWAIT 

No synchronisation mode 


Return value 

The file descriptor is returned when successful, and -1 in the event of failure. 

See Also 


close() 





close 


Structure 


Arguments 


Comments 


Return value 


See Also 


int close ( 
int fd 
) 


fd 


File descriptor 


close releases the fde descriptor. 


fd is returned when successful, and -1 in all other cases. 


Closing file 


openQ 




lseek 


Moving file pointer 


Structure 

int lseek ( 
int fd, 

unsigned int offset, 
int flag 
) 


Arguments 


fd 

File descriptor 

offset 

Offset 

flag 

Refer to the comments 


Comments 

lseek moves the file pointer of the device showing the descriptor specified byfd. 
offset is the movement byte number. The movement start point changes according to the 
value of flag. 

It cannot be applied to character type drivers. 

Macros that can be specified inflag are as follows. 


Flag 

Macro function 

SEEKSET 

Top of file 

SEEKCUR 

Current location 


Return value 


The current file pointer is returned when successful, and -1 in all other cases. 





See Also 


openQ, readQ, write() 



read 


Structure 


Arguments 


Comments 


Return value 


See Also 


Reads data from file 


int read ( 


int fd, 


char *buf 


int n 


) 


fd 

File descriptor 

buf 

Read buffer address 

n 

Read byte number 


read reads n bytes from the descriptor specified byfd to the buf specified area. 


The byte number read in the area at the time of normal termination is returned, and - 1 in 
all other cases. 


openQ 




write 


Structure 


Arguments 


Comments 


Return value 


See Also 


Writes data to file 


int write ( 


int fd, 


char *buf 


int n 


) 


fd 

File descriptor 

buf 

Write data address 

n 

Write byte number 


write writes n bytes from the descriptor specified byfd to the buf specified area. 


The byte number written in the area at the time of normal termination is returned, and -1 
in all other cases. 


openQ 




fir stfile 


First file retrieval 


Structure 

struct DIRENTRY *firstfile ( 
char *name, 
struct DIRENTRY tiir 
) 

Arguments 

name Filename 

dir Buffer that stores information relating to retrievable files 


Comments 

firstfile retrieves files corresponding to the filename pattemname, and stores information 
relating to them in dir. 


Return value 

dir is returned when successful, and 0 in all other cases. 


Notes 

(one optional character) * (entire character string of optional length) can be used as a 
wildcard character in the filename pattern. The character specification after * is 
disregarded. 

See Also 


DIRENTRY structure, nextfile() 




nextfile 


Next file retrieval 


Structure 

struct DIRENTRY *nexttfile ( 
struct DIRENTRY ’tiir 
) 

Arguments 

dir Buffer that stores information relating to retrievable files 


Comments 

nextfile continuously carries out retrieval in the same way as the firstfile() function 
executed directly before. When relevant files are found, information relating to them is 
stored in dir. 


Return value 

dir is returned when successful, and 0 in all other cases. 


Notes 

Execution will be unsuccessful if the CD-ROM drive shell cover is opened after firstfile(), 
and there will be a report that the file cannot be found. 


See Also 


DIRENTRY structure, firstfile() 




delete 


Structure 


Arguments 


Comments 


Return value 


Deletes files 


int delete ( 
char *name 
) 


name 


Filename 


delete deletes the file name 


1 is returned when successful, and 0 in all other cases. 




format 


Structure 


Arguments 


Comments 


Return value 


Notes 


int format ( 
char *fs 
) 


fs 


File system name 


format initialises the file system fs. 


1 is returned when successful, and 0 in all other cases. 


Initialises file system 


Valid only for file systems that can be written. 




rename 


Renaming files 


Structure 

int rename ( 
char *src, 
char *dest 
) 


Source filename 
New filename 


Arguments 


src 

dest 


Comments 

rename changes the filename fromsrc to dest. It specifies the full path from the device 
name to both src and dest. 


Return value 

1 is returned when successful, and 0 in all other cases. 


Notes 


Valid only for file systems that can be written. 




LoadTest 


Load test execution 


Structure 

long LoadTest ( 
char *name, 
struct EXEC *exec 
) 

Arguments 

name Filename 

exec Executable file information 

Comments 

LoadTest writes the information contained in the PS-EXE format filaiameto exec. 

Return value 

The execution start address is returned when successful, and 0 if unsuccessful. 

See Also 

EXEC structure, LoadQ 




Load 


Structure 


Arguments 


Comments 


Return value 


See Also 


Loading executable file 


long Load ( 
char *name, 
struct EXEC *exec 
) 

name Filename 

exec Executable file information 


Load reads the PS-EXE format filename in the address specified by its internal header, 
and writes the internal information to exec. 


1 is returned when successful, and 0 if unsuccessful. 


EXEC structure, ExecQ 




Exec 


Executing executable files 


Structure 

long Exec ( 
struct EXEC *exec, 
long argc, 
char *argv 
) 

Arguments 


exec 

Executable file information 

argc 

Argument number 

argv 

Argument 


Comments 

Exec executes the module loaded on the memory in accordance with the executable file 
information specified byexec. 

Neither the stack nor the frame buffer are set ifexec->s addr is 0. 

The contents of the operation are as follows. 

(1) Data session is zero cleared without an initial value. 

(2) sp, fp and gp are initialised after evacuation (the value of fp is equal to 
that of sp) 

(3) The argument of main() is set (by the aO and al registers) 

(4) The execution start address is called. 

(5) sp, fp and gp are returned after return. 




Return value 

1 is returned when successful, and 0 in the event of failure. 

Notes 

Must be executed by critical section. 

See Also 

EXEC structure, LoadQ 



InitHeap 


Initialisation of heap area 


Structure 

void InitHeap ( 
void *head, 
long size 
) 

Arguments 

head Heap head address 

size Heap size (multiples of 4 byte units) 


Comments 

InitHeap initialises the group of memory control functions. Thereafter, malloc(), etc. can 
be used. Not all the size bytes can be used because of the presence of overhead. 


Return value 

None 


Notes 

Do not carry out multiple execution. 


See Also 


malloc() 




FlushCache 


Flushing I cache 


Structure 


void FlushCache ( void ) 


Arguments 

None 


Comments 

FlushCache flushes the I cache. 

It is executed when the program code is written in the memory. 


Return value 

None 


Notes 


Memory content cannot be changed. 




get_errno 


Gets adjacent input/output error code 


Structure 


long getermo ( void ) 


Arguments 

None 


Comments 

get ermo gets adjacent error code through all file descriptors. 
The error code is defined in sys/errno.h. 


Return value 


Error code 



GetPadBuf 


Gets controller buffers 


Structure 

void GetPadBuf ( 
volatile unsigned char **bufl, 
volatile unsigned char **buf2 
) 

Arguments 

bufl Pointer to the buffer that stores data from the port 1 controller. 

buf2 Pointer to the buffer that stores data from the port 2 controller. 


Comments 


Communication with the controller is carried out every vertical synchronisation 
interruption, and the result stored in controller buffers within the system. The GetPadBuf 
function can get the pointers to those buffers. 

Two sets of controller buffers are available for the ports, and the following data is stored. 




Bytes 

Content 

0 

Oxff: Without controller 


0x00: With controller 

1 

Upper 4bit: Terminal type 


Lower 4bit: Received data size (1/2 byte number) 

2~ 

Reception data (largest 32 bytes) 


The received data is different according to the controller type shown by ‘terminal type’. 
The terminal types supported by this library are as follows. 


Terminal Classification 

Device Name 

0x1 

Mouse 

0x2 

NeGCon 

0x4 

Standard controller 

0x5 

Joystick 


Please refer to the "Programmer's Guide" for the contents of received data corresponding 
to terminal type. 


Return value 


None 




CdPlay 


Plays back CD-DA tracks 


Structure 

int CdPlay ( 
int mode, 
int * tracks, 
int offset 
) 


Arguments 

mode Mode 

tracks Array that specifies track to be played. Ends with 0. 

offset index of tracks starting the performance 


Comments 

CdPlay plays consecutively in the background multiple tracks specified by the array 
tracks. When the last track of the array is played, it repeats or ends the performance, 
according to the mode. 

Values that can be specified in mode are as follows. 


Value 

Description 

0 

Stops performance 

1 

The tracks specified byxacks are played consecutively, and the performance is stopped 
when all the specified tracks have been played. 

2 

The tracks specified byxacks are played consecutively, and the performance is returnee 
to the start and repeated when all the specified tracks have been played. 

3 

The index of thetracks array for the track currently being played is returned. 













Return value 

The track currently being played. The index of thetracks array is returned instead of the 
track number. The performance is shown as ended if -1 is returned. 


Notes 

The performance is carried out in track units, Performance and stopping etc. in mid track 
is not possible. 



CdReadFile 


Reads files on CD-ROM 


Structure 


Arguments 


int CdReadFile( 


char *file, 


u_long *addr, 


int nbyte 


) 


file 

Filename 

addr 

Read memory address 

nbyte 

Read size 


Comments 

CdReadFile reads nbyte of a file on CD-ROM. 

The entire file is read if 0 is specified in nbyte. 

If NULL is specified infile, reading starts from the last location read by CdReadFile 
immediately before. 


Return value 

The data number (bytes) read is returned if successful, and 0 is returned in the case of a 
reading error. 




Notes 


The filename must be an absolute path. 

Lower case characters are automatically changed to upper case characters. 

Reading is carried out in the background, and CdReadSync() is used to determine the end 
of reading. 



CdReadExec 


Loading executable files from CD-ROM 


Structure 

struct EXEC *CdReadExec( 
char *file 
) 


Arguments 

file 


Executable filename 


Comments 

Executable files specified byfile are loaded by CdReadExec from CD-ROM to the 
appropriate address in the main memory. 

Reading is carried out in the background, and CdReadSync() is used to determine the end 
of reading. 

The loaded file is executed as a child process by using ExecQ. 


Return value 

EXEC structure that holds executable files that have been read. 


Notes 

The load address of the executable file should not overlap the area used by the parent 


process 




CdReadSync 


Waits for termination of CdRead 


Structure 

int CdReadSync ( 
int mode, 
u_char *result 
) 


0: Waits for termination of read 

1: Current condition is checked and immediately returned 
Status of most recently terminated command 


Arguments 

mode 


result 


Comments 

CdReadSync waits for reading by CdReadFile() and CdReadExecQ to terminate. 


Return value 

The following values are returned. 


Return value 

Content 

Standard integer 

Remaining sector number 

0 

Termination 

-1 

Read error 












CdSearchFile 


Gets location and size from filename on CD-ROM 


Structure 

CdlFILE *CdSearchFile ( 
CdlFILE *fp, 
char *name 
) 


Arguments 

ip CD-ROM file structure pointer 

name Filename 


Comments 

CdSearchFile recognises the absolute location (minute, second, sector) and size from the 
filename on CD-ROM. 

The result is stored in ip. 


Return value 

The pointer of the CD-ROM file structure obtained is returned. 

0 is returned if the file is not found, and -1 is returned if the search fails. 


Notes 

The filename must be an absolute path. 

File location information in the same directory as files specified byfp are cached in 
memory. For this reason, if CdSearchFile() is carried out continuously in files within the 
same directory, access becomes faster from the second time. 

Cases where the return value is -1 show that the directory read has failed for some reason. 




GetVideoModeQ 


Obtains the present video signalling system 


Structure 

long GetVideoMode (void) 


Arguments 

None 


Comments 

Returns the present video signaling system declared in SetVideoMode(). 


Return value 

Return value contents is the video signaling system mode 

MODE_NTSC: NTSC system video signaling system 

MODE_PAL: PAL system video signaling system 


Notes 

When SetVideoMode () is not called, no matter what the machine, it will return 
MODE NTSC. 


See Also 


SetVideoModeQ 




SetVideoModeQ 


Declares current video signalling system 


Structure 

long SetVideoMode ( 
long mode 
) 

Arguments 

mode Video signaling system mode 


Comments 

Declares the video signaling system indicated bymode to the libraries. 

Related libraries will be able to conform to the actions of the declared video signaling 
system environment. 


Return value 

Previously-set video signaling system mode 
Mode Contents 

MODE_NTSC: NTSC system video signaling sytem 

MODEPAL: PAL system video signaling system 


Notes 

Gets called in advance of all library functions. 


See Also 


GetVideoModeQ 




TestCard 


Memory card test 


Structure 

long TestCard ( 
long chan 
) 

Arguments 

chan Slot numbers 

0: Slot 1 
1: Slot 2 

Comments 

TestCard tests the memory card set in the slot specified bychan and returns the result. 

Card initialisation is carried out on the memory card control screen of the PlayStation. 
One to four vertical synchronisation interruptions at the end of the operation are necessary 
(17m to 68m seconds). 


Return value 

0: No card 
1: Card present 
2: New card detected 

3: Communication or card abnormality detected 
Non-initialised card detected 


4 : 
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